lora-python 0.5.0__tar.gz → 0.5.1__tar.gz

{lora_python-0.5.0 → lora_python-0.5.1}/Cargo.lock

@@ -651,7 +651,7 @@ checksum = "5e5032e24019045c762d3c0f28f5b6b8bbf38563a65908389bf7978758920897"
 
 [[package]]
 name = "lora-analyzer"
-version = "0.5.0"
+version = "0.5.1"
 dependencies = [
  "lora-ast",
  "lora-parser",
@@ -661,14 +661,14 @@ dependencies = [
 
 [[package]]
 name = "lora-ast"
-version = "0.5.0"
+version = "0.5.1"
 dependencies = [
  "smallvec 2.0.0-alpha.12",
 ]
 
 [[package]]
 name = "lora-compiler"
-version = "0.5.0"
+version = "0.5.1"
 dependencies = [
  "lora-analyzer",
  "lora-ast",
@@ -676,7 +676,7 @@ dependencies = [
 
 [[package]]
 name = "lora-database"
-version = "0.5.0"
+version = "0.5.1"
 dependencies = [
  "anyhow",
  "criterion",
@@ -694,7 +694,7 @@ dependencies = [
 
 [[package]]
 name = "lora-executor"
-version = "0.5.0"
+version = "0.5.1"
 dependencies = [
  "lora-analyzer",
  "lora-ast",
@@ -708,7 +708,7 @@ dependencies = [
 
 [[package]]
 name = "lora-ffi"
-version = "0.5.0"
+version = "0.5.1"
 dependencies = [
  "lora-database",
  "lora-store",
@@ -718,7 +718,7 @@ dependencies = [
 
 [[package]]
 name = "lora-node"
-version = "0.5.0"
+version = "0.5.1"
 dependencies = [
  "anyhow",
  "lora-database",
@@ -732,7 +732,7 @@ dependencies = [
 
 [[package]]
 name = "lora-parser"
-version = "0.5.0"
+version = "0.5.1"
 dependencies = [
  "lora-ast",
  "pest",
@@ -743,7 +743,7 @@ dependencies = [
 
 [[package]]
 name = "lora-python"
-version = "0.5.0"
+version = "0.5.1"
 dependencies = [
  "anyhow",
  "lora-database",
@@ -755,7 +755,7 @@ dependencies = [
 
 [[package]]
 name = "lora-server"
-version = "0.5.0"
+version = "0.5.1"
 dependencies = [
  "anyhow",
  "axum",
@@ -769,7 +769,7 @@ dependencies = [
 
 [[package]]
 name = "lora-store"
-version = "0.5.0"
+version = "0.5.1"
 dependencies = [
  "bincode",
  "crc32fast",
@@ -781,7 +781,7 @@ dependencies = [
 
 [[package]]
 name = "lora-wal"
-version = "0.5.0"
+version = "0.5.1"
 dependencies = [
  "bincode",
  "crc32fast",
@@ -792,7 +792,7 @@ dependencies = [
 
 [[package]]
 name = "lora-wasm"
-version = "0.5.0"
+version = "0.5.1"
 dependencies = [
  "anyhow",
  "console_error_panic_hook",
@@ -807,7 +807,7 @@ dependencies = [
 
 [[package]]
 name = "lora_ruby"
-version = "0.5.0"
+version = "0.5.1"
 dependencies = [
  "anyhow",
  "lora-database",

{lora_python-0.5.0 → lora_python-0.5.1}/Cargo.toml

@@ -4,7 +4,7 @@ resolver = "2"
 
 [workspace.package]
 edition = "2021"
-version = "0.5.0"
+version = "0.5.1"
 license = "BUSL-1.1"
 authors = ["LoraDB, Inc."]
 repository = "https://github.com/lora-db/lora"
@@ -15,14 +15,14 @@ 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.5.0" }
-lora-parser = { path = "crates/lora-parser", version = "=0.5.0" }
-lora-analyzer = { path = "crates/lora-analyzer", version = "=0.5.0" }
-lora-compiler = { path = "crates/lora-compiler", version = "=0.5.0" }
-lora-store = { path = "crates/lora-store", version = "=0.5.0" }
-lora-wal = { path = "crates/lora-wal", version = "=0.5.0" }
-lora-executor = { path = "crates/lora-executor", version = "=0.5.0" }
-lora-database = { path = "crates/lora-database", version = "=0.5.0" }
+lora-ast = { path = "crates/lora-ast", version = "=0.5.1" }
+lora-parser = { path = "crates/lora-parser", version = "=0.5.1" }
+lora-analyzer = { path = "crates/lora-analyzer", version = "=0.5.1" }
+lora-compiler = { path = "crates/lora-compiler", version = "=0.5.1" }
+lora-store = { path = "crates/lora-store", version = "=0.5.1" }
+lora-wal = { path = "crates/lora-wal", version = "=0.5.1" }
+lora-executor = { path = "crates/lora-executor", version = "=0.5.1" }
+lora-database = { path = "crates/lora-database", version = "=0.5.1" }
 
 # External crates.
 anyhow = "1"

{lora_python-0.5.0 → lora_python-0.5.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: lora-python
-Version: 0.5.0
+Version: 0.5.1
 Classifier: Programming Language :: Rust
 Classifier: Programming Language :: Python :: 3
 Classifier: Programming Language :: Python :: 3.8
@@ -70,11 +70,11 @@ Initialization rule:
 from lora_python import Database
 
 scratch = Database.create()            # in-memory
-persistent = Database.create("./app")  # persistent: directory string
+persistent = Database.create("app", {"database_dir": "./data"})  # persistent: ./data/app.loradb
 ```
 
-If you want persistence, pass a directory string to `Database.create(...)`
-or `Database(...)`.
+If you want persistence, pass a database name and `database_dir` to
+`Database.create(...)` or `Database(...)`.
 
 ## Async usage (non-blocking)
 
@@ -95,7 +95,7 @@ Async initialization follows the same rule:
 
 ```python
 db = await AsyncDatabase.create()            # in-memory
-db = await AsyncDatabase.create("./app")     # persistent: directory string
+db = await AsyncDatabase.create("app", {"database_dir": "./data"})  # persistent: ./data/app.loradb
 ```
 
 `AsyncDatabase.execute` dispatches the query onto the default asyncio
@@ -146,16 +146,16 @@ All three are available as `lora_python.LoraError`, etc.
 
 ## Persistence
 
-`Database.create("./app")`, `Database("./app")`, and
-`await AsyncDatabase.create("./app")` open or create a WAL-backed
-persistent database rooted at that directory. Reopening the same path
+`Database.create("app", {"database_dir": "./data"})`, `Database("app", {"database_dir": "./data"})`, and
+`await AsyncDatabase.create("app", {"database_dir": "./data"})` open or create
+an archive-backed persistent database at `./data/app.loradb`. Reopening the same path
 replays committed writes before returning the handle.
 
-Call `db.close()` / `await db.close()` before reopening the same WAL
-directory inside one process.
+Call `db.close()` / `await db.close()` before reopening the same archive
+inside one process.
 
 This first Python persistence slice intentionally stays small: the
-binding exposes WAL-backed initialization plus the existing
+binding exposes archive-backed initialization plus the existing
 `save_snapshot` / `load_snapshot` APIs, but not checkpoint, truncate,
 status, or sync-mode controls.
 

{lora_python-0.5.0 → lora_python-0.5.1}/README.md

@@ -40,11 +40,11 @@ Initialization rule:
 from lora_python import Database
 
 scratch = Database.create()            # in-memory
-persistent = Database.create("./app")  # persistent: directory string
+persistent = Database.create("app", {"database_dir": "./data"})  # persistent: ./data/app.loradb
 ```
 
-If you want persistence, pass a directory string to `Database.create(...)`
-or `Database(...)`.
+If you want persistence, pass a database name and `database_dir` to
+`Database.create(...)` or `Database(...)`.
 
 ## Async usage (non-blocking)
 
@@ -65,7 +65,7 @@ Async initialization follows the same rule:
 
 ```python
 db = await AsyncDatabase.create()            # in-memory
-db = await AsyncDatabase.create("./app")     # persistent: directory string
+db = await AsyncDatabase.create("app", {"database_dir": "./data"})  # persistent: ./data/app.loradb
 ```
 
 `AsyncDatabase.execute` dispatches the query onto the default asyncio
@@ -116,16 +116,16 @@ All three are available as `lora_python.LoraError`, etc.
 
 ## Persistence
 
-`Database.create("./app")`, `Database("./app")`, and
-`await AsyncDatabase.create("./app")` open or create a WAL-backed
-persistent database rooted at that directory. Reopening the same path
+`Database.create("app", {"database_dir": "./data"})`, `Database("app", {"database_dir": "./data"})`, and
+`await AsyncDatabase.create("app", {"database_dir": "./data"})` open or create
+an archive-backed persistent database at `./data/app.loradb`. Reopening the same path
 replays committed writes before returning the handle.
 
-Call `db.close()` / `await db.close()` before reopening the same WAL
-directory inside one process.
+Call `db.close()` / `await db.close()` before reopening the same archive
+inside one process.
 
 This first Python persistence slice intentionally stays small: the
-binding exposes WAL-backed initialization plus the existing
+binding exposes archive-backed initialization plus the existing
 `save_snapshot` / `load_snapshot` APIs, but not checkpoint, truncate,
 status, or sync-mode controls.
 

{lora_python-0.5.0 → lora_python-0.5.1}/crates/lora-database/benches/wal_benchmarks.rs

@@ -204,7 +204,7 @@ fn bench_named_archive_write_heavy(c: &mut Criterion) {
 
     // One timed iteration performs a realistic write burst. For the
     // persistent variant, dropping the DB at the end joins the archive writer
-    // and includes the final `.lora` ZIP flush, so the result measures more
+    // and includes the final `.loradb` ZIP flush, so the result measures more
     // than just "enqueue dirty flag".
     const WRITES: usize = 1_000;
 

{lora_python-0.5.0 → lora_python-0.5.1}/crates/lora-database/src/archive.rs

@@ -15,11 +15,11 @@ const MANIFEST_JSON: &str = r#"{"format":"lora.archive","version":1}"#;
 const WAL_PREFIX: &str = "wal/";
 const ARCHIVE_FLUSH_DEBOUNCE: Duration = Duration::from_secs(1);
 
-/// ZIP-backed `.lora` database file.
+/// ZIP-backed `.loradb` database file.
 ///
 /// Every persist rewrites a complete ZIP archive from the current WAL work
 /// directory to a temp file, fsyncs it, and atomically renames it over the
-/// `.lora` target. Any ZIP-compatible tool (WinRAR, Explorer, unzip, 7-Zip)
+/// `.loradb` target. Any ZIP-compatible tool (WinRAR, Explorer, unzip, 7-Zip)
 /// can inspect the resulting database file.
 pub(crate) struct WalArchive {
     work_dir: PathBuf,
@@ -108,6 +108,12 @@ impl Drop for WalArchive {
         {
             let (lock, cv) = &*self.state;
             let mut state = lock.lock().unwrap();
+            // The async archive worker may have already consumed the dirty flag
+            // before Group-mode WAL bytes were forced out of the in-memory
+            // segment buffer. Drop runs after the WAL handle is dropped, so
+            // always take one final archive snapshot from the now-flushed work
+            // directory.
+            state.dirty = true;
             state.shutdown = true;
             state.force = true;
             cv.notify_one();
@@ -191,7 +197,7 @@ fn write_archive_atomic(
     archive_path: &Path,
     max_archive_bytes: u64,
 ) -> Result<(), WalError> {
-    let tmp_path = archive_path.with_extension("lora.tmp");
+    let tmp_path = archive_path.with_extension("loradb.tmp");
     {
         let file = OpenOptions::new()
             .create(true)

{lora_python-0.5.0 → lora_python-0.5.1}/crates/lora-database/src/database.rs

@@ -85,9 +85,9 @@ impl Database<InMemoryGraph> {
     /// Open or create a named portable database rooted under
     /// `options.database_dir`.
     ///
-    /// The database name is a logical identifier, not a path. It must contain
-    /// only ASCII letters, digits, `_`, `-`, and `.`, and is resolved to
-    /// `<database_dir>/<database_name>.lora` before the WAL backend opens.
+    /// The database name may be either a portable basename (`app` or
+    /// `app.loradb`) or a safe relative path (`tenant/app`). It is resolved
+    /// under `options.database_dir` before the WAL archive backend opens.
     pub fn open_named(
         database_name: impl AsRef<str>,
         options: DatabaseOpenOptions,

lora_python-0.5.1/crates/lora-database/src/named.rs

@@ -0,0 +1,204 @@
+use std::fmt;
+use std::path::{Path, PathBuf};
+
+use lora_wal::{SyncMode, WalConfig};
+
+/// Hard ceiling for one portable database archive/root.
+///
+/// The current WAL backend still stores segment files under this root, but
+/// callers should treat the resolved `.loradb` path as the database artifact.
+/// The archive backend will use the same limit when it starts writing framed
+/// compressed chunks directly into portable files.
+pub const DEFAULT_DATABASE_MAX_BYTES: u64 = 4 * 1024 * 1024 * 1024;
+
+/// Options for opening a named filesystem-backed database.
+#[derive(Debug, Clone)]
+pub struct DatabaseOpenOptions {
+    pub database_dir: PathBuf,
+    pub sync_mode: SyncMode,
+    pub segment_target_bytes: u64,
+    pub max_database_bytes: u64,
+}
+
+impl Default for DatabaseOpenOptions {
+    fn default() -> Self {
+        Self {
+            database_dir: PathBuf::from("."),
+            sync_mode: SyncMode::Group { interval_ms: 1_000 },
+            segment_target_bytes: 8 * 1024 * 1024,
+            max_database_bytes: DEFAULT_DATABASE_MAX_BYTES,
+        }
+    }
+}
+
+impl DatabaseOpenOptions {
+    pub fn with_database_dir(mut self, database_dir: impl Into<PathBuf>) -> Self {
+        self.database_dir = database_dir.into();
+        self
+    }
+
+    pub fn wal_config_for(&self, name: &DatabaseName) -> WalConfig {
+        WalConfig::Enabled {
+            dir: self.database_path_for(name),
+            sync_mode: self.sync_mode,
+            segment_target_bytes: self.segment_target_bytes,
+        }
+    }
+
+    pub fn database_path_for(&self, name: &DatabaseName) -> PathBuf {
+        self.database_dir.join(name.relative_path())
+    }
+}
+
+/// Validated logical database name/path.
+///
+/// The input is serialized as a safe relative path under
+/// [`DatabaseOpenOptions::database_dir`]. For example:
+///
+/// - `app` -> `app.loradb`
+/// - `app.loradb` -> `app.loradb`
+/// - `./tenant-a/app` -> `tenant-a/app.loradb`
+///
+/// Absolute paths, parent-directory traversal, empty components, and characters
+/// outside ASCII letters/digits plus `+`, `_`, `-` are rejected. The final path
+/// component may additionally end in `.loradb`.
+#[derive(Debug, Clone, PartialEq, Eq, PartialOrd, Ord, Hash)]
+pub struct DatabaseName {
+    raw: String,
+    relative_path: PathBuf,
+}
+
+impl DatabaseName {
+    pub fn parse(value: impl AsRef<str>) -> Result<Self, DatabaseNameError> {
+        let value = value.as_ref();
+        if value.is_empty() {
+            return Err(DatabaseNameError::Empty);
+        }
+
+        if value.starts_with('/') || value.starts_with('\\') || looks_like_windows_absolute(value) {
+            return Err(DatabaseNameError::AbsolutePath(value.to_string()));
+        }
+
+        let mut parts: Vec<&str> = value.split(['/', '\\']).collect();
+        if parts.iter().any(|part| part.is_empty()) {
+            return Err(DatabaseNameError::InvalidCharacters(value.to_string()));
+        }
+        while parts.first() == Some(&".") {
+            parts.remove(0);
+        }
+        while parts.last() == Some(&".") {
+            parts.pop();
+        }
+        if parts.is_empty() {
+            return Err(DatabaseNameError::Reserved(value.to_string()));
+        }
+
+        let mut path = PathBuf::new();
+        for (idx, part) in parts.iter().enumerate() {
+            if *part == "." {
+                continue;
+            }
+            if *part == ".." {
+                return Err(DatabaseNameError::Reserved(value.to_string()));
+            }
+            let is_basename = idx == parts.len() - 1;
+            let serialized = serialize_component(part, is_basename)
+                .ok_or_else(|| DatabaseNameError::InvalidCharacters(value.to_string()))?;
+            path.push(serialized);
+        }
+        if path.as_os_str().is_empty() {
+            return Err(DatabaseNameError::Reserved(value.to_string()));
+        }
+        Ok(Self {
+            raw: value.to_string(),
+            relative_path: path,
+        })
+    }
+
+    pub fn as_str(&self) -> &str {
+        &self.raw
+    }
+
+    pub fn relative_path(&self) -> &Path {
+        &self.relative_path
+    }
+}
+
+impl fmt::Display for DatabaseName {
+    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
+        self.raw.fmt(f)
+    }
+}
+
+impl TryFrom<&str> for DatabaseName {
+    type Error = DatabaseNameError;
+
+    fn try_from(value: &str) -> Result<Self, Self::Error> {
+        Self::parse(value)
+    }
+}
+
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub enum DatabaseNameError {
+    Empty,
+    Reserved(String),
+    AbsolutePath(String),
+    InvalidCharacters(String),
+}
+
+impl fmt::Display for DatabaseNameError {
+    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
+        match self {
+            Self::Empty => write!(f, "database name must not be empty"),
+            Self::Reserved(name) => write!(f, "database name '{name}' is reserved"),
+            Self::AbsolutePath(name) => write!(
+                f,
+                "invalid database name '{name}': use a relative path under database_dir"
+            ),
+            Self::InvalidCharacters(name) => write!(
+                f,
+                "invalid database name '{name}': use relative path components containing only letters, digits, '+', '_', '-', with an optional .loradb suffix on the basename"
+            ),
+        }
+    }
+}
+
+impl std::error::Error for DatabaseNameError {}
+
+pub fn resolve_database_path(
+    database_name: &str,
+    database_dir: impl AsRef<Path>,
+) -> Result<PathBuf, DatabaseNameError> {
+    let name = DatabaseName::parse(database_name)?;
+    Ok(database_dir.as_ref().join(name.relative_path()))
+}
+
+fn serialize_component(component: &str, is_basename: bool) -> Option<String> {
+    if component.is_empty() {
+        return None;
+    }
+
+    if is_basename {
+        if let Some(stem) = component.strip_suffix(".loradb") {
+            return (!stem.is_empty() && is_portable_component(stem))
+                .then(|| component.to_string());
+        }
+        return is_portable_component(component).then(|| format!("{component}.loradb"));
+    }
+
+    is_portable_component(component).then(|| component.to_string())
+}
+
+fn is_portable_component(value: &str) -> bool {
+    value
+        .bytes()
+        .all(|b| b.is_ascii_alphanumeric() || matches!(b, b'+' | b'_' | b'-'))
+}
+
+fn looks_like_windows_absolute(value: &str) -> bool {
+    let bytes = value.as_bytes();
+    bytes.len() >= 3
+        && bytes[0].is_ascii_alphabetic()
+        && bytes[1] == b':'
+        && matches!(bytes[2], b'/' | b'\\')
+}

{lora_python-0.5.0 → lora_python-0.5.1}/crates/lora-database/tests/wal.rs

@@ -90,14 +90,34 @@ fn disabled_config_behaves_like_in_memory() {
 
 #[test]
 fn database_name_validation_accepts_only_portable_names() {
-    for valid in ["app", "tenant_01", "a-b.c", "A123"] {
+    for valid in [
+        "app",
+        "app.loradb",
+        "tenant_01",
+        "tenant+01",
+        "a-b",
+        "A123",
+        "./database-dir/application",
+        "database_dir/app.loradb",
+    ] {
         assert!(
             DatabaseName::parse(valid).is_ok(),
             "{valid} should be valid"
         );
     }
 
-    for invalid in ["", ".", "..", "../x", "x/y", "has space", "ümlaut"] {
+    for invalid in [
+        "",
+        ".",
+        "..",
+        "../x",
+        "/absolute/app",
+        "x//y",
+        "a-b.c",
+        "app.txt",
+        "has space",
+        "ümlaut",
+    ] {
         assert!(
             DatabaseName::parse(invalid).is_err(),
             "{invalid:?} should be invalid"
@@ -109,7 +129,13 @@ fn database_name_validation_accepts_only_portable_names() {
 fn named_database_resolves_to_lora_root_under_database_dir() {
     let dir = TmpDir::new("named-path");
     let path = resolve_database_path("app_01", dir.path()).unwrap();
-    assert_eq!(path, dir.path().join("app_01.lora"));
+    assert_eq!(path, dir.path().join("app_01.loradb"));
+
+    let path = resolve_database_path("./tenant-a/application", dir.path()).unwrap();
+    assert_eq!(path, dir.path().join("tenant-a").join("application.loradb"));
+
+    let path = resolve_database_path("tenant_b/app.loradb", dir.path()).unwrap();
+    assert_eq!(path, dir.path().join("tenant_b").join("app.loradb"));
 }
 
 #[test]
@@ -126,12 +152,12 @@ fn named_database_persists_under_lora_root() {
     }
 
     assert!(
-        dir.path().join("app.lora").is_file(),
-        "named databases should persist as a portable .lora archive file"
+        dir.path().join("app.loradb").is_file(),
+        "named databases should persist as a portable .loradb archive file"
     );
-    let bytes = std::fs::read(dir.path().join("app.lora")).unwrap();
+    let bytes = std::fs::read(dir.path().join("app.loradb")).unwrap();
     assert_eq!(&bytes[..4], b"PK\x03\x04");
-    let file = std::fs::File::open(dir.path().join("app.lora")).unwrap();
+    let file = std::fs::File::open(dir.path().join("app.loradb")).unwrap();
     let mut zip = zip::ZipArchive::new(file).unwrap();
     assert!(zip.by_name("manifest.json").is_ok());
     assert!(zip.by_name("wal/0000000001.wal").is_ok());
@@ -161,7 +187,7 @@ fn named_database_recovers_write_burst_from_zip_archive() {
         assert_eq!(db.node_count(), 250);
     }
 
-    let archive_path = dir.path().join("burst.lora");
+    let archive_path = dir.path().join("burst.loradb");
     assert!(archive_path.is_file());
     let file = std::fs::File::open(&archive_path).unwrap();
     let mut zip = zip::ZipArchive::new(file).unwrap();
@@ -183,6 +209,44 @@ fn named_database_recovers_write_burst_from_zip_archive() {
     assert_eq!(row_array.last().unwrap()["id"], serde_json::json!(249));
 }
 
+#[test]
+fn named_database_final_archive_flush_captures_group_buffer() {
+    let dir = TmpDir::new("named-group-final-flush");
+
+    {
+        let db = Database::open_named(
+            "app",
+            DatabaseOpenOptions {
+                database_dir: dir.path().to_path_buf(),
+                sync_mode: SyncMode::Group {
+                    interval_ms: 60_000,
+                },
+                ..DatabaseOpenOptions::default()
+            },
+        )
+        .unwrap();
+        db.execute(
+            "CREATE (:Person {name: 'Ada'})-[:KNOWS]->(:Person {name: 'Grace'})",
+            rows(),
+        )
+        .unwrap();
+
+        // Let the archive debounce worker observe the dirty flag before the
+        // Group-mode WAL flusher runs. The final archive flush on drop must
+        // still snapshot the force-flushed WAL bytes, not the earlier empty
+        // segment file.
+        std::thread::sleep(std::time::Duration::from_millis(1_200));
+    }
+
+    let db = Database::open_named(
+        "app",
+        DatabaseOpenOptions::default().with_database_dir(dir.path()),
+    )
+    .unwrap();
+    assert_eq!(db.node_count(), 2);
+    assert_eq!(db.relationship_count(), 1);
+}
+
 #[test]
 fn fresh_open_then_crash_recover_replays_committed_writes() {
     let dir = TmpDir::new("recover");