diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 3887e53..4d815f1 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -2,7 +2,7 @@ name: CI on: push: - branches: [main] + branches: [main, v3] pull_request: workflow_call: inputs: @@ -34,3 +34,31 @@ jobs: targets: aarch64-apple-ios-sim - name: Build for iOS simulator run: cargo build --target aarch64-apple-ios-sim --release + + # Compiles the generated Swift bindings with Sources/MinigrafKit and runs + # Tests/swift/main.swift against a macOS build of the shim. + swift-test: + name: Swift bindings test (macOS) + runs-on: macos-14 + steps: + - uses: actions/checkout@v4 + with: + ref: ${{ inputs.ref }} + - uses: dtolnay/rust-toolchain@stable + - name: Build shim (release) + run: cargo build --release + - name: Generate Swift bindings + run: | + cargo run --release --bin uniffi-bindgen -- generate \ + --library target/release/libminigraf_ffi.dylib \ + --language swift \ + --out-dir build/swift + - name: Compile and run Swift tests + run: | + swiftc -module-name MinigrafKit \ + -I build/swift \ + -Xcc -fmodule-map-file=build/swift/minigraf_ffiFFI.modulemap \ + -L target/release -lminigraf_ffi \ + build/swift/minigraf_ffi.swift Sources/MinigrafKit/*.swift Tests/swift/main.swift \ + -o build/swift-test + DYLD_LIBRARY_PATH=target/release ./build/swift-test diff --git a/Cargo.lock b/Cargo.lock index 23bbad8..b0b7b80 100644 --- a/Cargo.lock +++ b/Cargo.lock @@ -440,8 +440,7 @@ checksum = "f8ca58f447f06ed17d5fc4043ce1b10dd205e060fb3ce5b979b8ed8e59ff3f79" [[package]] name = "minigraf" version = "2.0.3" -source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "f46a3a991ca47660196a3595826a080fc31f1a0f0d9a1dd043969e96a18d1fa4" +source = "git+https://github.com/project-minigraf/minigraf?rev=97cd4a2a85301ea3478250dd654139d45a1f7cd0#97cd4a2a85301ea3478250dd654139d45a1f7cd0" dependencies = [ "anyhow", "chrono", diff --git a/Cargo.toml b/Cargo.toml index 845d050..37f9fe8 100644 --- a/Cargo.toml +++ b/Cargo.toml @@ -16,7 +16,8 @@ path = "src/uniffi_bindgen.rs" [dependencies] # Pin to the exact released version. The release workflow updates this line. -minigraf = "=2.0.3" +# Unreleased v3 core (format v8). Switches to minigraf = "=3.0.0" at the v3.0.0 release. +minigraf = { git = "https://github.com/project-minigraf/minigraf", rev = "97cd4a2a85301ea3478250dd654139d45a1f7cd0" } uniffi = { version = "0.31.1", features = ["cli"] } thiserror = "2.0.18" serde_json = "1.0.149" diff --git a/README.md b/README.md index b6d8a8c..71e473d 100644 --- a/README.md +++ b/README.md @@ -51,6 +51,33 @@ let result = try db.execute(datalog: #"(transact [[:alice :name "Alice"]])"#) print(result) // {"transacted":1} ``` +## Open options, cursors, the fact log and the log writer + +```swift +import MinigrafKit + +// Read-only: shared lock, nothing written; writes throw MiniGrafError (API-014). +let src = try MiniGrafDb.openWithOptions(path: oldPath, options: OpenOptions(readOnly: true, pageCacheSize: 4096)) + +// A cursor's answer is fixed when it opens. Each batch is a JSON array of rows, +// encoded like execute()'s "results". +let cursor = try src.query(datalog: "(query [:find ?n :where [?e :name ?n]])") +try cursor.forEachBatch(size: 1000) { batch in /* parse rows */ } + +// Copy every fact version, keeping tx and valid-time bounds, into a new file. +let out = try MiniGrafLogWriter.create(path: newPath, options: OpenOptions()) +try src.factLog(filter: FactFilter()).forEachRecord { record in + if !record.attribute.hasPrefix(":secret/") { try out.append(record: record) } +} +try out.advanceTxCount(txCount: try src.currentTxCount()) +try out.finish() // out.close() instead abandons the build and leaves no file +``` + +`appendBatch(records:)` appends many records per call. A record's value is a +`MiniGrafValue` (`.text`, `.int64`, `.float64`, `.bool`, `.ref`, `.keyword`, `.null`); +`validTimeForever` is the `validTo` of a fact valid forever. `MiniGrafError.message` +starts with the error's code, such as `[API-015]`. + ## Building from source Requires Rust stable toolchain with iOS targets and Xcode. diff --git a/Sources/MinigrafKit/MinigrafKit+Iteration.swift b/Sources/MinigrafKit/MinigrafKit+Iteration.swift new file mode 100644 index 0000000..a658cf5 --- /dev/null +++ b/Sources/MinigrafKit/MinigrafKit+Iteration.swift @@ -0,0 +1,37 @@ +// Iteration helpers over the generated bindings. A Swift `Sequence` cannot +// throw, and a batch read can fail, so these take a throwing closure instead. + +extension MiniGrafCursor { + /// Calls `body` with each batch of at most `size` rows, as a JSON array of + /// rows encoded like `execute`'s `results`, until the cursor ends. + public func forEachBatch(size: Int32 = 1000, _ body: (String) throws -> Void) throws { + while let batch = try nextBatch(maxRows: size) { + try body(batch) + } + } +} + +extension MiniGrafFactLog { + /// Calls `body` with each record, reading `batchSize` records at a time, + /// until the log ends. + public func forEachRecord(batchSize: Int32 = 1000, _ body: (FactRecord) throws -> Void) throws { + while let batch = try nextBatch(maxRecords: batchSize) { + for record in batch { + try body(record) + } + } + } +} + +extension MiniGrafError { + /// The error's text, starting with its code, such as `[API-015]`. + public var message: String { + switch self { + case .Storage(let msg), .Query(let msg), .Parse(let msg), .Other(let msg): + return msg + } + } +} + +/// `validTo` of a fact that is valid forever. +public let validTimeForever: Int64 = Int64.max diff --git a/Tests/swift/main.swift b/Tests/swift/main.swift new file mode 100644 index 0000000..251476e --- /dev/null +++ b/Tests/swift/main.swift @@ -0,0 +1,133 @@ +// Run by CI (swift-test job): compiled together with the generated bindings and +// Sources/MinigrafKit into one module, linked against libminigraf_ffi. +import Foundation + +var failures = 0 +func check(_ condition: Bool, _ what: String, line: Int = #line) { + if !condition { + print("FAIL line \(line): \(what)") + failures += 1 + } +} + +func errorText(_ body: () throws -> Void) -> String { + do { + try body() + return "no error" + } catch let e as MiniGrafError { + return e.message + } catch { + return "unexpected error" + } +} + +let dir = FileManager.default.temporaryDirectory.appendingPathComponent(UUID().uuidString) +try FileManager.default.createDirectory(at: dir, withIntermediateDirectories: true) +func path(_ name: String) -> String { dir.appendingPathComponent(name).path } +let ref = "00000000-0000-4000-8000-000000000001" +let query = "(query [:find ?e ?n :where [?e :n ?n]])" + +// Cursor (#462) +do { + let db = try MiniGrafDb.openInMemory() + for i in 0..<25 { _ = try db.execute(datalog: "(transact [[:e\(i) :n \(i)]])") } + let all = try JSONSerialization.jsonObject(with: Data(try db.execute(datalog: query).utf8)) as! [String: Any] + let expected = (all["results"] as! [[Any]]).count + for size: Int32 in [1, 7, 1000] { + let cursor = try db.query(datalog: query) + check(cursor.vars() == ["?e", "?n"], "vars") + var rows = 0 + try cursor.forEachBatch(size: size) { batch in + let decoded = try JSONSerialization.jsonObject(with: Data(batch.utf8)) as! [[Any]] + check(!decoded.isEmpty && decoded.count <= Int(size), "batch size") + rows += decoded.count + } + check(rows == expected, "rows for batch size \(size)") + } + let fixed = try db.query(datalog: query) + _ = try db.execute(datalog: "(transact [[:late :n 99]])") + var fixedRows = 0 + try fixed.forEachBatch { fixedRows += (try JSONSerialization.jsonObject(with: Data($0.utf8)) as! [[Any]]).count } + check(fixedRows == 25, "cursor fixed at open") + let closed = try db.query(datalog: query) + closed.close() + check(try closed.nextBatch(maxRows: 1) == nil, "closed cursor ends") + check(errorText { _ = try db.query(datalog: "(transact [[:a :n 1]])") }.hasPrefix("[API-012]"), "API-012") +} + +// Open options (#465) +do { + let p = path("ro.graph") + do { + let db = try MiniGrafDb.open(path: p) + _ = try db.execute(datalog: "(transact [[:a :n 1] [:b :n 2]])") + try db.checkpoint() + } + let ro = try MiniGrafDb.openWithOptions(path: p, options: OpenOptions(readOnly: true, pageCacheSize: 16)) + let ro2 = try MiniGrafDb.openWithOptions(path: p, options: OpenOptions(readOnly: true)) + check(try ro.currentTxCount() == 1 && ro2.currentTxCount() == 1, "two read-only handles") + check(errorText { _ = try ro.execute(datalog: "(transact [[:c :n 3]])") }.hasPrefix("[API-014]"), "API-014") + check(errorText { _ = try MiniGrafDb.open(path: p) }.hasPrefix("[STG-02"), "writer refused") + let missing = path("missing.graph") + check(errorText { _ = try MiniGrafDb.openWithOptions(path: missing, options: OpenOptions(readOnly: true)) }.hasPrefix("[STG-042]"), "STG-042") + check(!FileManager.default.fileExists(atPath: missing), "missing file not created") +} + +// Fact log and log writer (#467) +do { + let src = try MiniGrafDb.open(path: path("src.graph")) + _ = try src.execute(datalog: #"(transact {:valid-from "2024-01-01" :valid-to "2025-01-01"} [[:alice :name "Alice"] [:alice :tag :t/admin]])"#) + _ = try src.execute(datalog: "(transact [[:bob :friend #uuid \"\(ref)\"] [:bob :score 2.5]])") + _ = try src.execute(datalog: #"(retract [[:alice :name "Alice"]])"#) + + func records(_ db: MiniGrafDb, _ filter: FactFilter = FactFilter()) throws -> [FactRecord] { + var out: [FactRecord] = [] + try db.factLog(filter: filter).forEachRecord(batchSize: 2) { out.append($0) } + return out + } + let recs = try records(src) + check(recs.count == 5, "five records") + check(recs.map(\.txCount) == recs.map(\.txCount).sorted(), "tx order") + check(recs.first { $0.attribute == ":friend" }?.value == .ref(value: ref), "ref value") + check(recs.first { $0.attribute == ":tag" }?.value == .keyword(value: ":t/admin"), "keyword value") + check(recs.first { $0.attribute == ":score" }?.validTo == validTimeForever, "forever") + check(try records(src, FactFilter(txFrom: 2, txTo: 2)).allSatisfy { $0.txCount == 2 }, "tx filter") + check(errorText { _ = try src.factLog(filter: FactFilter(entities: ["alice"])) }.hasPrefix("[API-017]"), "API-017") + + let out = path("out.graph") + let w = try MiniGrafLogWriter.create(path: out, options: OpenOptions()) + try w.append(record: recs[0]) + try w.appendBatch(records: Array(recs.dropFirst())) + try w.advanceTxCount(txCount: try src.currentTxCount()) + check(try w.txCount() == 3, "writer tx_count") + try w.finish() + check(errorText { try w.finish() }.hasPrefix("[API-018]"), "API-018") + let copy = try MiniGrafDb.openWithOptions(path: out, options: OpenOptions(readOnly: true)) + check(try copy.currentTxCount() == src.currentTxCount(), "copied tx count") + check(try records(copy) == recs, "copied records") + + let hole = path("hole.graph") + let h = try MiniGrafLogWriter.create(path: hole, options: OpenOptions()) + try h.appendBatch(records: recs.filter { $0.txCount != 2 }) + try h.advanceTxCount(txCount: 3) + try h.finish() + let hdb = try MiniGrafDb.openWithOptions(path: hole, options: OpenOptions(readOnly: true)) + check(Set(try records(hdb).map(\.txCount)) == [1, 3], "hole") + + let bad = path("bad.graph") + let b = try MiniGrafLogWriter.create(path: bad, options: OpenOptions()) + try b.append(record: recs.last!) + let order = errorText { try b.appendBatch(records: [recs.last!, recs.first!]) } + check(order.hasPrefix("[API-015]") && order.hasSuffix("(batch index 1)"), "API-015 batch index") + b.close() + check(!b.isOpen(), "closed writer") + check(!FileManager.default.fileExists(atPath: bad) && !FileManager.default.fileExists(atPath: bad + ".partial"), "abandoned build leaves no file") + check(errorText { _ = try MiniGrafLogWriter.create(path: out, options: OpenOptions()) }.hasPrefix("[STG-043]"), "STG-043") +} + +try? FileManager.default.removeItem(at: dir) +if failures > 0 { + print("\(failures) check(s) failed") + exit(1) +} +print("all Swift checks passed") diff --git a/src/lib.rs b/src/lib.rs index a43fc9e..25114c1 100644 --- a/src/lib.rs +++ b/src/lib.rs @@ -12,7 +12,7 @@ )] use minigraf::{QueryResult, Value}; -use std::sync::{Arc, Mutex}; +use std::sync::{Arc, Mutex, MutexGuard}; uniffi::setup_scaffolding!(); @@ -48,6 +48,286 @@ impl From for MiniGrafError { } } +impl MiniGrafError { + /// Append the position of the rejected record to the message. + fn at_batch_index(self, index: usize) -> Self { + let suffix = |msg: String| format!("{msg} (batch index {index})"); + match self { + MiniGrafError::Storage { msg } => MiniGrafError::Storage { msg: suffix(msg) }, + MiniGrafError::Query { msg } => MiniGrafError::Query { msg: suffix(msg) }, + MiniGrafError::Parse { msg } => MiniGrafError::Parse { msg: suffix(msg) }, + MiniGrafError::Other { msg } => MiniGrafError::Other { msg: suffix(msg) }, + } + } +} + +fn lock(m: &Mutex) -> Result, MiniGrafError> { + m.lock().map_err(|_| MiniGrafError::Other { + msg: "mutex poisoned".into(), + }) +} + +// Counts cross the FFI as signed integers: Kotlin's unsigned types cannot be +// called from Java. A negative or oversized count is API-017. + +fn to_u64(n: i64, what: &str) -> Result { + u64::try_from(n).map_err(|_| { + minigraf::MinigrafError::invalid_argument(format!("{what} {n} is negative")).into() + }) +} + +fn to_usize(n: i64, what: &str) -> Result { + usize::try_from(to_u64(n, what)?).map_err(|_| { + minigraf::MinigrafError::invalid_argument(format!("{what} {n} is too large")).into() + }) +} + +/// A transaction counter or timestamp for the FFI. Both stay far below +/// `i64::MAX` (a counter of one per transaction; Unix milliseconds). +fn from_u64(n: u64) -> i64 { + i64::try_from(n).unwrap_or(i64::MAX) +} + +fn parse_uuid(s: &str, what: &str) -> Result { + minigraf::EntityId::parse_str(s).map_err(|_| { + minigraf::MinigrafError::invalid_argument(format!("{what} {s:?} is not a UUID")) + }) +} + +// ─── Open options ──────────────────────────────────────────────────────────── + +/// WAL durability mode. See the Rust `SyncMode`. +#[derive(Debug, Clone, Copy, PartialEq, Eq, uniffi::Enum)] +pub enum SyncMode { + /// Flush the WAL after every write (the default). + Full, + /// Flush only at checkpoints. + Normal, +} + +/// Options for `MiniGrafDb.open_with_options` and `MiniGrafLogWriter.create`. +/// Every field is optional; an absent field keeps the Rust default. +#[derive(Debug, Clone, Default, uniffi::Record)] +pub struct OpenOptions { + /// Open read-only: shared lock, nothing written, writes fail with API-014. + #[uniffi(default)] + pub read_only: Option, + /// Pages (4 KB each) in the page cache. Default 256. + #[uniffi(default)] + pub page_cache_size: Option, + /// Open even when the filesystem cannot lock files. Default false. + #[uniffi(default)] + pub allow_unlocked: Option, + /// WAL entries before an automatic checkpoint. Default 1000; the maximum + /// value also suppresses the checkpoint on close. + #[uniffi(default)] + pub wal_checkpoint_threshold: Option, + /// Facts a recursive rule may derive per iteration. Default 1,000,000. + #[uniffi(default)] + pub max_derived_facts: Option, + /// Rows a query may return. Default 1,000,000. + #[uniffi(default)] + pub max_results: Option, + /// WAL durability. Default `Full`. + #[uniffi(default)] + pub synchronous: Option, +} + +impl OpenOptions { + fn to_core(&self) -> Result { + let mut o = minigraf::OpenOptions::new(); + if let Some(v) = self.read_only { + o = o.read_only(v); + } + if let Some(v) = self.page_cache_size { + o = o.page_cache_size(to_usize(v, "page_cache_size")?); + } + if let Some(v) = self.allow_unlocked { + o = o.allow_unlocked(v); + } + if let Some(v) = self.wal_checkpoint_threshold { + o = o.wal_checkpoint_threshold(to_usize(v, "wal_checkpoint_threshold")?); + } + if let Some(v) = self.max_derived_facts { + o = o.max_derived_facts(to_usize(v, "max_derived_facts")?); + } + if let Some(v) = self.max_results { + o = o.max_results(to_usize(v, "max_results")?); + } + if let Some(v) = self.synchronous { + o = o.synchronous(match v { + SyncMode::Full => minigraf::SyncMode::Full, + SyncMode::Normal => minigraf::SyncMode::Normal, + }); + } + Ok(o) + } +} + +// ─── Values and fact records ───────────────────────────────────────────────── + +/// A fact value with its type kept, so a record can be written back exactly. +/// `Ref` holds an entity UUID string. +#[derive(Debug, Clone, PartialEq, uniffi::Enum)] +pub enum MiniGrafValue { + Text { value: String }, + Int64 { value: i64 }, + Float64 { value: f64 }, + Bool { value: bool }, + Ref { value: String }, + Keyword { value: String }, + Null, +} + +impl From for MiniGrafValue { + fn from(v: Value) -> Self { + match v { + Value::String(value) => MiniGrafValue::Text { value }, + Value::Integer(value) => MiniGrafValue::Int64 { value }, + Value::Float(value) => MiniGrafValue::Float64 { value }, + Value::Boolean(value) => MiniGrafValue::Bool { value }, + Value::Ref(id) => MiniGrafValue::Ref { + value: id.to_string(), + }, + Value::Keyword(value) => MiniGrafValue::Keyword { value }, + Value::Null => MiniGrafValue::Null, + } + } +} + +impl MiniGrafValue { + fn to_core(&self) -> Result { + Ok(match self { + MiniGrafValue::Text { value } => Value::String(value.clone()), + MiniGrafValue::Int64 { value } => Value::Integer(*value), + MiniGrafValue::Float64 { value } => Value::Float(*value), + MiniGrafValue::Bool { value } => Value::Boolean(*value), + MiniGrafValue::Ref { value } => Value::Ref(parse_uuid(value, "ref value")?), + MiniGrafValue::Keyword { value } => Value::Keyword(value.clone()), + MiniGrafValue::Null => Value::Null, + }) + } +} + +/// One fact-log record: an assertion or a retraction, with its transaction +/// and valid-time bounds. `valid_to` = 9223372036854775807 (i64 max) is forever. +#[derive(Debug, Clone, PartialEq, uniffi::Record)] +pub struct FactRecord { + /// The entity UUID string. + pub entity: String, + pub attribute: String, + pub value: MiniGrafValue, + pub tx_count: i64, + pub tx_id: i64, + pub valid_from: i64, + pub valid_to: i64, + pub asserted: bool, +} + +impl From for FactRecord { + fn from(r: minigraf::FactRecord) -> Self { + FactRecord { + entity: r.entity.to_string(), + attribute: r.attribute, + value: r.value.into(), + tx_count: from_u64(r.tx_count), + tx_id: from_u64(r.tx_id), + valid_from: r.valid_from, + valid_to: r.valid_to, + asserted: r.asserted, + } + } +} + +impl FactRecord { + fn to_core(&self) -> Result { + let count = |n: i64, what: &str| { + u64::try_from(n).map_err(|_| { + minigraf::MinigrafError::invalid_argument(format!("{what} {n} is negative")) + }) + }; + Ok(minigraf::FactRecord { + entity: parse_uuid(&self.entity, "entity")?, + attribute: self.attribute.clone(), + value: self.value.to_core()?, + tx_count: count(self.tx_count, "tx_count")?, + tx_id: count(self.tx_id, "tx_id")?, + valid_from: self.valid_from, + valid_to: self.valid_to, + asserted: self.asserted, + }) + } +} + +/// The order of a fact log. +#[derive(Debug, Clone, Copy, PartialEq, Eq, uniffi::Enum)] +pub enum FactOrder { + /// Ascending `tx_count`, each transaction's records together (the default). + Tx, + /// The cheapest order to read, in one scan. + Storage, +} + +/// Which records a fact log returns. Every field is optional; the ones that +/// are set must all match. +#[derive(Debug, Clone, Default, uniffi::Record)] +pub struct FactFilter { + /// Keep these attributes (combined with `attribute_prefixes`, either matches). + #[uniffi(default)] + pub attributes: Option>, + /// Keep attributes starting with one of these, such as `":ingestion/"`. + #[uniffi(default)] + pub attribute_prefixes: Option>, + /// Keep these entity UUID strings. + #[uniffi(default)] + pub entities: Option>, + /// Lowest `tx_count` kept (inclusive). + #[uniffi(default)] + pub tx_from: Option, + /// Highest `tx_count` kept (inclusive). + #[uniffi(default)] + pub tx_to: Option, + #[uniffi(default)] + pub order: Option, + /// In `Tx` order, the most records held in memory at once. + #[uniffi(default)] + pub window: Option, +} + +impl FactFilter { + fn to_core(&self) -> Result { + let mut f = minigraf::FactFilter::new(); + if let Some(attrs) = &self.attributes { + f = f.attributes(attrs.iter().cloned()); + } + for prefix in self.attribute_prefixes.iter().flatten() { + f = f.attribute_prefix(prefix); + } + if let Some(entities) = &self.entities { + let ids = entities + .iter() + .map(|e| parse_uuid(e, "entity")) + .collect::, _>>()?; + f = f.entities(ids); + } + if self.tx_from.is_some() || self.tx_to.is_some() { + let lo = self.tx_from.map_or(Ok(0), |n| to_u64(n, "tx_from"))?; + let hi = self.tx_to.map_or(Ok(u64::MAX), |n| to_u64(n, "tx_to"))?; + f = f.tx_range(lo..=hi); + } + if let Some(order) = self.order { + f = f.order(match order { + FactOrder::Tx => minigraf::FactOrder::Tx, + FactOrder::Storage => minigraf::FactOrder::Storage, + }); + } + if let Some(w) = self.window { + f = f.window(to_usize(w, "window")?); + } + Ok(f) + } +} + // ─── MiniGrafDb ────────────────────────────────────────────────────────────── #[derive(uniffi::Object)] @@ -85,6 +365,43 @@ impl MiniGrafDb { Ok(query_result_to_json(result)) } + /// Open a file-backed database with `options`. + #[uniffi::constructor] + pub fn open_with_options( + path: String, + options: OpenOptions, + ) -> Result, MiniGrafError> { + let db = minigraf::Minigraf::open_with_options(&path, options.to_core()?) + .map_err(MiniGrafError::from)?; + Ok(Arc::new(Self { + inner: Arc::new(Mutex::new(db)), + })) + } + + /// Open a cursor over a `(query ...)`. Its answer is fixed when it opens. + pub fn query(&self, datalog: String) -> Result, MiniGrafError> { + let cursor = lock(&self.inner)?.query(&datalog)?; + Ok(Arc::new(MiniGrafCursor { + vars: cursor.vars().to_vec(), + inner: Mutex::new(Some(cursor)), + })) + } + + /// Stream every fact record that `filter` keeps. Checkpoints wait until + /// the log is closed or read to the end. + pub fn fact_log(&self, filter: FactFilter) -> Result, MiniGrafError> { + let filter = filter.to_core()?; + let log = lock(&self.inner)?.fact_log(&filter)?; + Ok(Arc::new(MiniGrafFactLog { + inner: Mutex::new(Some(log)), + })) + } + + /// The transaction counter that `:as-of N` compares against. + pub fn current_tx_count(&self) -> Result { + Ok(from_u64(lock(&self.inner)?.current_tx_count())) + } + pub fn checkpoint(&self) -> Result<(), MiniGrafError> { self.inner .lock() @@ -96,8 +413,182 @@ impl MiniGrafDb { } } +// ─── MiniGrafCursor ────────────────────────────────────────────────────────── + +/// The rows of one query answer, in batches. +#[derive(uniffi::Object)] +pub struct MiniGrafCursor { + vars: Vec, + /// `None` after `close()` or the end. + inner: Mutex>, +} + +#[uniffi::export] +impl MiniGrafCursor { + /// The `:find` variables, in column order. + pub fn vars(&self) -> Vec { + self.vars.clone() + } + + /// The next batch of at most `max_rows` rows (0 counts as 1), as a JSON + /// array of rows encoded like `execute()`'s `results`; `None` at the end + /// or after `close()`. A batch is never empty. + pub fn next_batch(&self, max_rows: i32) -> Result, MiniGrafError> { + let mut guard = lock(&self.inner)?; + let Some(cursor) = guard.as_mut() else { + return Ok(None); + }; + match cursor.next_batch(to_usize(i64::from(max_rows), "max_rows")?)? { + Some(batch) => Ok(Some(rows_to_json(batch.rows()))), + None => { + *guard = None; + Ok(None) + } + } + } + + /// Release the cursor. Later `next_batch` calls return `None`. + pub fn close(&self) { + if let Ok(mut guard) = self.inner.lock() { + *guard = None; + } + } +} + +// ─── MiniGrafFactLog ───────────────────────────────────────────────────────── + +/// A forward-only stream of fact records from `MiniGrafDb.fact_log`. +#[derive(uniffi::Object)] +pub struct MiniGrafFactLog { + /// `None` after `close()` or the end, which releases the database. + inner: Mutex>, +} + +#[uniffi::export] +impl MiniGrafFactLog { + /// The next batch of at most `max_records` records (0 counts as 1); + /// `None` at the end or after `close()`. A batch is never empty. + pub fn next_batch(&self, max_records: i32) -> Result>, MiniGrafError> { + let mut guard = lock(&self.inner)?; + let Some(log) = guard.as_mut() else { + return Ok(None); + }; + match log.next_batch(to_usize(i64::from(max_records), "max_records")?) { + Ok(Some(batch)) => Ok(Some(batch.into_iter().map(FactRecord::from).collect())), + Ok(None) => { + *guard = None; + Ok(None) + } + Err(e) => { + *guard = None; + Err(e.into()) + } + } + } + + /// Stop reading and release the database. + pub fn close(&self) { + if let Ok(mut guard) = self.inner.lock() { + *guard = None; + } + } +} + +// ─── MiniGrafLogWriter ─────────────────────────────────────────────────────── + +/// Builds a new database file from fact records, keeping their transaction +/// and valid-time bounds. The file is built at `.partial` and renamed +/// into place by `finish()`. +#[derive(uniffi::Object)] +pub struct MiniGrafLogWriter { + /// `None` after `finish()` or `close()`. + inner: Mutex>, +} + +fn writer_closed() -> MiniGrafError { + minigraf::MinigrafError::closed("log writer").into() +} + +#[uniffi::export] +impl MiniGrafLogWriter { + /// Start building a new database at `path` (STG-043 if it exists). + #[uniffi::constructor] + pub fn create(path: String, options: OpenOptions) -> Result, MiniGrafError> { + let writer = minigraf::LogWriter::create(&path, options.to_core()?)?; + Ok(Arc::new(Self { + inner: Mutex::new(Some(writer)), + })) + } + + /// Append one record. A rejected record changes nothing. + pub fn append(&self, record: FactRecord) -> Result<(), MiniGrafError> { + let record = record.to_core()?; + let mut guard = lock(&self.inner)?; + let writer = guard.as_mut().ok_or_else(writer_closed)?; + Ok(writer.append(&record)?) + } + + /// Append `records` in order, stopping at the first rejected one. Its + /// error ends with `(batch index N)`; the records before it stay appended. + pub fn append_batch(&self, records: Vec) -> Result<(), MiniGrafError> { + let mut guard = lock(&self.inner)?; + let writer = guard.as_mut().ok_or_else(writer_closed)?; + for (i, record) in records.iter().enumerate() { + record + .to_core() + .and_then(|r| writer.append(&r)) + .map_err(|e| MiniGrafError::from(e).at_batch_index(i))?; + } + Ok(()) + } + + /// Close the open transaction and raise the counter to `tx_count`. + pub fn advance_tx_count(&self, tx_count: i64) -> Result<(), MiniGrafError> { + let tx_count = to_u64(tx_count, "tx_count")?; + let mut guard = lock(&self.inner)?; + let writer = guard.as_mut().ok_or_else(writer_closed)?; + Ok(writer.advance_tx_count(tx_count)?) + } + + /// The highest `tx_count` appended or advanced to. + pub fn tx_count(&self) -> Result { + let guard = lock(&self.inner)?; + Ok(from_u64( + guard.as_ref().ok_or_else(writer_closed)?.tx_count(), + )) + } + + /// Commit every record and rename the file into place. Later calls are + /// API-018. + pub fn finish(&self) -> Result<(), MiniGrafError> { + let writer = lock(&self.inner)?.take().ok_or_else(writer_closed)?; + Ok(writer.finish()?) + } + + /// Abandon an unfinished build, deleting `.partial`. A no-op after + /// `finish()` or `close()`. + pub fn close(&self) { + if let Ok(mut guard) = self.inner.lock() { + guard.take(); + } + } + + /// `false` once `finish()` or `close()` has been called. + pub fn is_open(&self) -> bool { + self.inner.lock().is_ok_and(|g| g.is_some()) + } +} + // ─── JSON serialisation (internal helpers) ─────────────────────────────────── +fn rows_to_json(rows: &[Vec]) -> String { + let rows: Vec> = rows + .iter() + .map(|row| row.iter().map(value_to_json).collect()) + .collect(); + serde_json::Value::from(rows).to_string() +} + fn value_to_json(v: &Value) -> serde_json::Value { use serde_json::Value as JVal; match v { @@ -188,8 +679,8 @@ mod tests { #[test] fn value_to_json_float_finite() { - let j = value_to_json(&Value::Float(3.14)); - assert_eq!(j, serde_json::json!(3.14)); + let j = value_to_json(&Value::Float(2.5)); + assert_eq!(j, serde_json::json!(2.5)); } #[test] @@ -315,6 +806,147 @@ mod tests { let _ = std::fs::remove_file(wal); } + fn err(r: Result) -> E { + match r { + Ok(_) => panic!("expected an error"), + Err(e) => e, + } + } + + fn msg(e: MiniGrafError) -> String { + match e { + MiniGrafError::Storage { msg } + | MiniGrafError::Query { msg } + | MiniGrafError::Parse { msg } + | MiniGrafError::Other { msg } => msg, + } + } + + #[test] + fn value_round_trips_through_core() { + let id = minigraf::EntityId::new_v4(); + for v in [ + Value::String("s".into()), + Value::Integer(-3), + Value::Float(2.5), + Value::Boolean(true), + Value::Ref(id), + Value::Keyword(":k/w".into()), + Value::Null, + ] { + let back = MiniGrafValue::from(v.clone()).to_core().expect("to_core"); + assert!(back == v, "value changed in round trip"); + } + } + + #[test] + fn bad_uuid_is_api_017() { + let e = err(MiniGrafValue::Ref { + value: "nope".into(), + } + .to_core()); + assert_eq!(e.code(), "API-017"); + let filter = FactFilter { + entities: Some(vec!["nope".into()]), + ..FactFilter::default() + }; + assert!(msg(err(filter.to_core())).starts_with("[API-017]")); + } + + #[test] + fn negative_counts_are_api_017() { + let options = OpenOptions { + page_cache_size: Some(-1), + ..OpenOptions::default() + }; + assert!(msg(err(options.to_core())).starts_with("[API-017]")); + let db = MiniGrafDb::open_in_memory().expect("open"); + let cursor = db + .query("(query [:find ?e :where [?e :n _]])".into()) + .expect("query"); + assert!(msg(err(cursor.next_batch(-1))).starts_with("[API-017]")); + } + + #[test] + fn cursor_batches_and_closes() { + let db = MiniGrafDb::open_in_memory().expect("open"); + for i in 0..5 { + db.execute(format!("(transact [[:e{i} :n {i}]])")) + .expect("transact"); + } + let cursor = db + .query("(query [:find ?n :where [?e :n ?n]])".into()) + .expect("query"); + assert_eq!(cursor.vars(), vec!["?n".to_string()]); + let mut rows = 0; + while let Some(batch) = cursor.next_batch(2).expect("batch") { + let batch: Vec> = serde_json::from_str(&batch).expect("json"); + assert!(!batch.is_empty() && batch.len() <= 2); + rows += batch.len(); + } + assert_eq!(rows, 5); + let cursor = db + .query("(query [:find ?n :where [?e :n ?n]])".into()) + .expect("query"); + cursor.close(); + assert!(cursor.next_batch(1).expect("closed").is_none()); + let e = err(db.query("(transact [[:a :n 1]])".into())); + assert!(msg(e).starts_with("[API-012]")); + } + + #[test] + fn fact_log_to_log_writer_round_trip() { + let dir = std::env::temp_dir().join(format!("minigraf_ffi_etl_{}", std::process::id())); + let _ = std::fs::remove_dir_all(&dir); + std::fs::create_dir_all(&dir).expect("dir"); + let src = MiniGrafDb::open_in_memory().expect("open"); + src.execute(r#"(transact [[:a :name "A"] [:a :n 1]])"#.into()) + .expect("transact"); + src.execute(r#"(retract [[:a :n 1]])"#.into()) + .expect("retract"); + let log = src.fact_log(FactFilter::default()).expect("log"); + let records = log.next_batch(100).expect("batch").expect("records"); + assert!(log.next_batch(100).expect("end").is_none()); + assert_eq!(records.len(), 3); + + let out = dir.join("out.graph").to_str().expect("utf8").to_string(); + let w = MiniGrafLogWriter::create(out.clone(), OpenOptions::default()).expect("create"); + let e = err(w.append_batch(vec![records[2].clone(), records[0].clone()])); + let e = msg(e); + assert!(e.starts_with("[API-015]") && e.ends_with("(batch index 1)")); + w.close(); + assert!(!w.is_open()); + assert!(msg(err(w.finish())).starts_with("[API-018]")); + assert!(!std::path::Path::new(&out).exists()); + + let w = MiniGrafLogWriter::create(out.clone(), OpenOptions::default()).expect("create"); + w.append_batch(records.clone()).expect("append"); + assert_eq!(w.tx_count().expect("tx_count"), 2); + w.finish().expect("finish"); + assert!(msg(err(w.tx_count())).starts_with("[API-018]")); + + let copy = MiniGrafDb::open_with_options( + out.clone(), + OpenOptions { + read_only: Some(true), + ..OpenOptions::default() + }, + ) + .expect("open copy"); + assert_eq!(copy.current_tx_count().expect("count"), 2); + let again = copy + .fact_log(FactFilter::default()) + .expect("log") + .next_batch(100) + .expect("batch") + .expect("records"); + assert!(again == records, "records changed in round trip"); + let e = err(copy.execute(r#"(transact [[:b :n 2]])"#.into())); + assert!(msg(e).starts_with("[API-014]")); + drop(copy); + let _ = std::fs::remove_dir_all(&dir); + } + #[test] fn checkpoint_in_memory_succeeds() { let db = MiniGrafDb::open_in_memory().expect("open");