From 11cd1a8542349dfce9ef5703f7828eef020ce57b Mon Sep 17 00:00:00 2001 From: Aditya Mukhopadhyay Date: Wed, 18 Nov 2026 08:21:41 +0530 Subject: [PATCH] fix(browser): fail the IndexedDB handle after a failed flush and settle every flush (#894) Backport of the v3 fix to format v7. An IndexedDB flush lands whole or not at all and always settles; after a failed flush the handle rejects further writes, checkpoints and imports with STG-046 until reopened, and the failure itself is STG-048. Registers STG-046 and STG-048 with their v3 meanings. Co-Authored-By: Claude Sonnet 5.5 --- CHANGELOG.md | 4 + CLAUDE.md | 4 +- Cargo.toml | 1 + README.md | 7 + ROADMAP.md | 11 + docs/ERROR_REFERENCE.md | 52 +++ docs/TEST_COVERAGE.md | 45 ++- scripts/check_browser_exports.py | 54 +++ src/browser/flush_tests.rs | 660 +++++++++++++++++++++++++++++++ src/browser/indexeddb.rs | 151 +++++-- src/browser/mod.rs | 186 +++++++-- src/error.rs | 18 + 12 files changed, 1114 insertions(+), 79 deletions(-) create mode 100644 scripts/check_browser_exports.py create mode 100644 src/browser/flush_tests.rs diff --git a/CHANGELOG.md b/CHANGELOG.md index b28b7a6ad0..d610387d34 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -7,6 +7,10 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 ## [Unreleased] +### Fixed + +- **IndexedDB flushes are atomic, settle on abort, and refuse later writes after a failure (#894)**, backported from v3 for the next v2.x patch. A synchronous exception while queueing pages aborts the whole batch; an abort with no request error rejects instead of hanging, and repeated request errors cannot throw from a consumed callback. The failed operation reports `STG-048` naming the IndexedDB write and browser exception (page-preparation errors retain their own code). Subsequent transact/retract, checkpoint and import calls report `STG-046` without changing memory. Overlapping flushes run in order; a checkpoint waits for earlier writes even when it has no dirty pages. Queries, rules and export remain available, including rejected work already applied in memory; export is not a durability acknowledgement. Discard the failed handle and reopen to recover the successful prefix before the failure. A failed import leaves IndexedDB unchanged. Format v7, the IndexedDB schema, public methods, healthy write volume and read-only open behavior are unchanged. Native v2.x behavior is unchanged; the two error codes retain their v3 meanings. + ### Documentation - Fix the Rust Quick Start (#884): register recursive rule clauses in separate `execute()` calls and define the keyword entity IDs used by prepared queries. Clarify the entity ID in the prepared-query error example. diff --git a/CLAUDE.md b/CLAUDE.md index eb0c8f65f6..92c8670af1 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -179,7 +179,7 @@ Auto-migrates v1/v2/v3/v4/v5/v6 → v7 on open/checkpoint. ## Test Coverage -**1335 tests** (1326 passing, 9 ignored; unit + integration + doc). +**1335 native tests** (1326 passing, 9 ignored; unit + integration + doc), plus **26 browser wasm-bindgen tests** (14 added for #894). See `docs/TEST_COVERAGE.md` for the full per-file breakdown. **Testing conventions** — see the Testing Conventions section below before writing any tests. @@ -188,6 +188,8 @@ Ordinary aggregates on v2 are `count`, `count-distinct`, `sum`, `sum-distinct`, ## Current Maintainer Context +**Unreleased, next v2.x patch** — the #894 IndexedDB backport makes flushes atomic and ordered, rejects abort-only failures, and refuses later durable work on a failed browser handle with STG-046. STG-048 names the failed IndexedDB write and DOM exception. Format v7 and the public API are unchanged. + **v2.0.11 released** (2026-10-26) — expression `=` / `!=` equates a keyword with a ref to its entity (#744), float-literal rule calls return `-0.0` rows in every run (#750), and `checkpoint` inside a `WriteTransaction` returns `INT-001` instead of deadlocking (#734). **v2.0.10 released** (2026-10-23) — WAL entries of more than 1,000,000 facts replay (#686), float constants match equal floats only (#706), prepared queries use the database's rule limits (#679); Kani proofs of `encode_value` backported (#627). **v2.0.9** (2026-10-21) — a pseudo-attribute in a rule body reads the stored fact (#661), a fact of more than four elements is rejected with PRS-108 (#649), `BrowserDb` rejections carry their error code (#673); every binding package is consumer-tested before and after publishing. **v2.0.8** (2026-10-20) — query data-integrity patch: `:db/valid-at` in `not-join` bodies and rule definitions (#615, #617), `or` branches with outer-variable expressions, `or`-bound expression variables and keyword/entity joins (#620, #625, #637), rules calling or recursing through a `not`/`or` rule (#628, #633). **v2.0.7** (2026-10-16) — prepared queries keep a literal `:as-of`/`:valid-at` (#603), rule calls with a literal argument return every row (#608), an `or` sharing no variable returns its cross product (#610). **v2.0.6** (2026-10-14) — concurrent-query data-integrity patch: queries see whole transactions (#554), one state per query (#555), no half-written checkpoint reads (#558). **v2.0.5** (2026-10-11) — short-file open refused with STG-045 (#506), commit after a torn WAL entry no longer lost, WAL-007 (#513); backported rule-query `max_results` (#528), all-checkpointed WAL removal (#457) and `usize::MAX` close-time save (#476); weekly soak test (#392), real coverage gates (#396). **v2.0.4** (2026-10-08) — `BrowserDb` IndexedDB flush returns an error for an unreadable dirty page (#470); golden-file v7 corpus (#391) and SIGKILL committed-data crash test (#384). **v2.0.3** (2026-10-06) — data-integrity patch under the support policy: indexed queries with >65,535 uncheckpointed facts (#445), tx counter rewound on reopen next to an already-checkpointed WAL (#447). **v2.0.2** (2026-09-27) — last planned v2.x feature/fix release: query fixes (#297, #405, #407, #410), directory fsync (#389), point-query/attribute-scan/checkpoint perf mitigations (#323, #381, #315), CI policy checks (#395), support policy and tiers (#397, #399, #400). **v2.0.1** (2026-09-25) fixed index rebuild on open (#370). **v2.0.0** introduced kernel file locking (#317, #304), structured runtime error codes (#277), `OpenOptions` `#[non_exhaustive]`, and an MSRV of Rust 1.89. See `CHANGELOG.md` for the full rationale and release history. Current plan (see `ROADMAP.md` and the milestones): diff --git a/Cargo.toml b/Cargo.toml index 2f53c61966..19b41e2ab5 100644 --- a/Cargo.toml +++ b/Cargo.toml @@ -54,6 +54,7 @@ web-sys = { version = "0.3", optional = true, features = [ "IdbOpenDbRequest", "IdbRequest", "IdbTransaction", + "DomException", "IdbTransactionMode", "Window", ] } diff --git a/README.md b/README.md index 1e4e004387..7659c13726 100644 --- a/README.md +++ b/README.md @@ -200,6 +200,13 @@ See the [Mobile Integration](https://project-minigraf.github.io/minigraf-docs/la ### For WASM / Browser +**Unreleased, next v2.x patch (#894):** after an IndexedDB flush fails, later +writes, checkpoints and imports reject with `STG-046`. Discard the handle and +reopen to recover the successful prefix before the failure. Queries, rules and +export remain usable; export includes rejected work still held in memory and +does not acknowledge durability. See the [changelog](CHANGELOG.md#unreleased) +and [error reference](docs/ERROR_REFERENCE.md#stg-046-earlier-checkpoint-or-indexeddb-flush-failed-on-this-handle). + Published as [`@minigraf/browser`](https://www.npmjs.com/package/@minigraf/browser) on npm (IndexedDB-backed, `wasm-pack`). WASI build (`wasm32-wasip1`) available as [`@minigraf/wasi`](https://www.npmjs.com/package/@minigraf/wasi) on npm and as a GitHub Releases artifact (Wasmtime / Wasmer). See the [Use Cases](https://project-minigraf.github.io/minigraf-docs/latest/use-cases/). The [playground](https://minigraf-playground.vercel.app/) and the [time travel visualizer](https://project-minigraf.github.io/minigraf-visualizer/) are both built on `@minigraf/browser`. ### For Python / Node.js / Java / C diff --git a/ROADMAP.md b/ROADMAP.md index 7213515db3..cfa8083393 100644 --- a/ROADMAP.md +++ b/ROADMAP.md @@ -8,6 +8,17 @@ Completed releases and their implementation details live in the [CHANGELOG](CHAN --- +## Next v2.x Patch — IndexedDB Durability (unreleased) + +Backport #894 from v3: atomic, always-settling IndexedDB flushes, ordered +persistence and checkpoint boundaries, and STG-046 refusal of later durable +work after a failed browser flush. The failure reports STG-048 (preparation +errors retain their engine code). Reopen recovers the successful prefix before +the failure. Format v7, IndexedDB schema, public methods and open behavior stay +unchanged. See [Unreleased](CHANGELOG.md#unreleased). + +--- + ## v2.0.11 — Query and Write-Transaction Patch (released 2026-10-26) File format stays v7 and the public API does not change. Details are in the [CHANGELOG](CHANGELOG.md). diff --git a/docs/ERROR_REFERENCE.md b/docs/ERROR_REFERENCE.md index 441e0ee6c7..12b7c6543d 100644 --- a/docs/ERROR_REFERENCE.md +++ b/docs/ERROR_REFERENCE.md @@ -138,6 +138,8 @@ with no `CodedError` anywhere in its chain. | STG-026 | Database locked by another process | Storage | | STG-027 | Filesystem does not support file locking | Storage | | STG-045 | File shorter than one page and not a new database | Storage | +| STG-046 | Earlier checkpoint or IndexedDB flush failed on this handle | Storage | +| STG-048 | Browser storage operation failed | Storage | | WAL-001 | Invalid WAL magic number | WAL | | WAL-002 | Unsupported WAL version | WAL | | WAL-003 | Fact serialised size exceeds maximum | WAL | @@ -2027,6 +2029,56 @@ See the [file format section in README](../README.md#file-format) for version hi --- +### STG-046 Earlier checkpoint or IndexedDB flush failed on this handle + +**Error text**: `an earlier checkpoint or IndexedDB flush failed on this handle and is not retried; reopen the database` + +**Cause**: In v2.x this code applies to `BrowserDb` backed by IndexedDB. A failed +flush rejects with STG-048, naming the IndexedDB write and DOM exception; a +failure preparing its pages keeps its engine code. The handle then refuses +newly admitted transact/retract, checkpoint and import operations with STG-046, +without changing facts, transaction counters or the live store. Native v2.x +handles do not use this failed-handle rule. + +Reads, rules and `exportGraph()` still work. Memory includes the failed operation +and overlapping work applied before the failure became known. Export reflects +that memory, not an acknowledgement of durability. Later flushes wait for earlier +ones and send nothing if an earlier flush failed. A checkpoint also waits for +writes applied before it, even when it has no dirty pages of its own. + +**Resolution**: +- Address the browser storage failure, discard the failed handle and open the + same name again. A fresh open loads the successful prefix before the failed + flush; a rejected IndexedDB write is never stored. There is no automatic retry. +- A failed import remains visible in memory, but leaves every byte in IndexedDB + unchanged. Use the fresh handle for subsequent writes. + +**Scenario**: A multi-page write exceeds the origin quota. It remains queryable +in memory, but every later durable operation is refused until the caller reopens. + +--- + +### STG-048 Browser storage operation failed + +**Error text**: `browser storage operation failed: {} ({})` + +**Cause**: An IndexedDB write failed during transaction creation, request +queueing, error or abort. The message names the operation (`IndexedDB write`) +and the browser exception (for example `QuotaExceededError` or `AbortError`). +None of the rejected flush's changes reach IndexedDB; even a synchronous +exception after earlier puts were queued aborts the whole transaction. + +**Resolution**: +- Check the operation and exception name, available origin quota and browser permissions. +- Later durable operations on this handle fail with STG-046. Discard it and reopen + to recover the successful prefix before the failed flush. Reads and export on + the failed handle may still include rejected work held only in memory. + +**Scenario**: Origin quota is exhausted while writing a data page; `execute()` +rejects with STG-048 naming the IndexedDB write and `QuotaExceededError`. + +--- + ## WAL — Write-Ahead Log Errors WAL errors relate to the sidecar `.wal` file written alongside the `.graph` file. diff --git a/docs/TEST_COVERAGE.md b/docs/TEST_COVERAGE.md index 60c0f49e39..2444cd14f0 100644 --- a/docs/TEST_COVERAGE.md +++ b/docs/TEST_COVERAGE.md @@ -2,11 +2,11 @@ #777 corrects documentation only on v2; query behavior and test counts are unchanged. Ordinary `avg` still raises PRS-027 without `:over`. -## v2.0.11 Coverage Summary +## Unreleased v2.x Coverage Summary | | | |---|---| -| **Verified** | 2026-10-26 with `cargo test` | +| **Verified** | 2026-11-18 with `cargo test` | | **Passing** | 1,326 | | **Ignored** | 9 (see [Ignored Tests](#ignored-tests)) | | **Total** | 1,335, including the golden-file corpus (#391) | @@ -155,12 +155,51 @@ These tests compare the database against an independent answer rather than a sin ### Browser -The `BrowserDb` tests run only on wasm32 with `wasm-bindgen-test` in a browser and are not in the counts above. +The **26 `BrowserDb` wasm-bindgen tests** (12 existing, 14 added for #894) run +only on wasm32 in a browser and are not in the native counts above. All 26 passed +in headless Firefox on 2026-11-18. - The IndexedDB flush returns every page a write dirtied. - A dirty page that cannot be read is an error rather than left out. - A parse, query and transact error reject with their codes (`PRS-011`, `QRY-007`, `PRS-046`), as on the native API (#673). +The #894 tests in `src/browser/flush_tests.rs` use real IndexedDB transactions +with test-only JavaScript interception. They cover abort-only settlement, +recoverable abort, multiple bubbling request errors, queue-time exceptions, +closed connections, a 400-fact failed write, checkpoint and smaller imports, +repeated STG-046 refusal without state changes, and INT-052 preparation failures. +Overlap cases cover write/write, write/import, import/write and write/checkpoint; +controls cover successful mixed operations, checkpoint boundaries excluding later +writes, earlier success before preparation failure, validation failures and +release of settled barriers. Queries, rules and export stay usable. Fresh open +performs no writeback and accepts subsequent writes. + +The quiescent oracle compares durable page bytes and recovered logical rows, +checks that every v7 header page reference is present, and exports the recovered +store. The verification run opened and queried **16 recovered exports with the +native CLI** using `scripts/check_browser_exports.py`. Export transport is opt-in: + +```bash +# Put matching wasm-bindgen-test-runner and geckodriver executables on PATH. +# The native binary and all scratch files remain under target/. +MINIGRAF_EXPORT_RECOVERY=1 WASM_BINDGEN_USE_BROWSER=1 MOZ_HEADLESS=1 \ +CARGO_TARGET_WASM32_UNKNOWN_UNKNOWN_RUNNER=wasm-bindgen-test-runner \ +cargo test --target wasm32-unknown-unknown --features browser --lib -- --nocapture > target/browser-exports.log 2>&1 +cargo build +python3 scripts/check_browser_exports.py target/browser-exports.log target/debug/minigraf +``` + +`wasm-pack test --headless --firefox --features browser` currently also compiles +native-only integration tests that call `Minigraf::open`, unavailable on wasm. +The direct library runner above exercises the browser suite without those tests. + +Before the production fix, the abort-only regression failed at its 1.5-second +deadline (`deadline: flush did not settle`), and the multi-page regression failed +because durable bytes had changed after the queue-time exception. Both pass with +the backport. v2 tests do not include v3 transactions, close, OPFS or open-time +migration flushes. Empty-file import cases use a real v7 header: importing zero +bytes on v2 sends no writes and cannot exercise an adapter failure. + ## Ignored Tests The nine ignored tests are intentionally excluded from a normal local run: diff --git a/scripts/check_browser_exports.py b/scripts/check_browser_exports.py new file mode 100644 index 0000000000..ec960edd80 --- /dev/null +++ b/scripts/check_browser_exports.py @@ -0,0 +1,54 @@ +#!/usr/bin/env python3 +"""Open recovered browser exports with the native CLI and compare their rows. + +Capture a successful browser test run with MINIGRAF_EXPORT_RECOVERY=1 and +--nocapture, then pass its log and the native minigraf binary to this script. +Only the Python standard library is needed. Scratch files stay under target/. +""" + +import argparse +import base64 +import json +from pathlib import Path +import subprocess +import tempfile + + +def main(): + parser = argparse.ArgumentParser(description=__doc__) + parser.add_argument("log", type=Path) + parser.add_argument("binary", type=Path) + args = parser.parse_args() + binary = args.binary.resolve() + target = Path(__file__).resolve().parents[1] / "target" + target.mkdir(exist_ok=True) + count = 0 + with tempfile.TemporaryDirectory(prefix="browser-exports-", dir=target) as scratch: + for line in args.log.read_text().splitlines(): + if not line.startswith("MINIGRAF_RECOVERED_EXPORT "): + continue + record = json.loads(line.split(" ", 1)[1]) + path = Path(scratch) / f"recovered-{count}.graph" + path.write_bytes(base64.b64decode(record["bytes"], validate=True)) + result = subprocess.run( + [str(binary), "--file", str(path)], + input="(query [:find ?n :where [?e :n ?n]])\n", + text=True, + capture_output=True, + check=True, + ) + if result.stderr: + raise RuntimeError(f"native open/query failed for export {count}: {result.stderr}") + rows = sorted( + int(row) for row in result.stdout.splitlines() if row.isdecimal() + ) + if rows != record["expected"]: + raise RuntimeError(f"native rows differ from the successful prefix in export {count}") + count += 1 + if not count: + raise RuntimeError("no exports found; enable MINIGRAF_EXPORT_RECOVERY=1 and --nocapture") + print(f"Native open and query passed for {count} recovered browser exports.") + + +if __name__ == "__main__": + main() diff --git a/src/browser/flush_tests.rs b/src/browser/flush_tests.rs new file mode 100644 index 0000000000..08c65b832d --- /dev/null +++ b/src/browser/flush_tests.rs @@ -0,0 +1,660 @@ +//! IndexedDB flush failures (#894). Faults wrap real browser transactions; +//! no injection controls are compiled into the library. +use super::*; +use crate::storage::StorageBackend; + +fn js_text(e: &JsValue) -> String { + e.as_string() + .unwrap_or_else(|| String::from(js_sys::JsString::from(e.clone()))) +} +use js_sys::{Function, Promise, Reflect, Uint8Array}; +use wasm_bindgen_futures::{JsFuture, future_to_promise}; +use wasm_bindgen_test::*; + +const QUERY: &str = "(query [:find ?n :where [?e :n ?n]])"; + +fn name() -> String { + format!( + "flush-894-{}-{}", + js_sys::Date::now(), + js_sys::Math::random() + ) +} + +fn write(first: usize, end: usize) -> String { + let facts: String = (first..end).map(|i| format!("[:e{i} :n {i}]")).collect(); + format!("(transact [{facts}])") +} + +/// A real empty v7 file, with a header page to flush. Unlike v3, importing +/// zero bytes on v2 has no dirty pages and sends no IndexedDB transaction. +fn empty_image() -> Uint8Array { + let mut bytes = crate::storage::FileHeader::new().to_bytes(); + bytes.resize(crate::storage::PAGE_SIZE, 0); + Uint8Array::from(bytes.as_slice()) +} + +fn code(result: Result, expected: &str) { + let Err(e) = result else { + panic!("expected rejection {expected}") + }; + let message = js_text(&e); + assert!(message.starts_with(&format!("[{expected}]")), "{message}"); +} + +/// A bounded wait also catches the old abort-only hang. Clear its timer on +/// either outcome so a passing test leaves no work behind. +async fn deadline(p: Promise) -> Result { + let bounded: Promise = Function::new_with_args( + "p", + r#" + return new Promise((resolve,reject) => { + const timer = setTimeout(() => reject('deadline: flush did not settle'), 1500); + p.then(v => { clearTimeout(timer); resolve(v); }, + e => { clearTimeout(timer); reject(e); }); + }); + "#, + ) + .call1(&JsValue::NULL, &p) + .unwrap() + .unchecked_into(); + JsFuture::from(bounded).await +} + +fn execute(db: &BrowserDb, command: String) -> Promise { + let inner = db.inner.clone(); + future_to_promise(async move { + BrowserDb { inner } + .execute(command) + .await + .map(JsValue::from) + }) +} + +fn checkpoint(db: &BrowserDb) -> Promise { + let inner = db.inner.clone(); + future_to_promise(async move { + BrowserDb { inner } + .checkpoint() + .await + .map(|()| JsValue::UNDEFINED) + }) +} + +fn import(db: &BrowserDb, bytes: Uint8Array) -> Promise { + let inner = db.inner.clone(); + future_to_promise(async move { + BrowserDb { inner } + .import_graph(bytes) + .await + .map(|()| JsValue::UNDEFINED) + }) +} + +async fn tick() { + JsFuture::from(Promise::resolve(&JsValue::NULL)) + .await + .unwrap(); +} + +async fn rows(db: &BrowserDb) -> Vec { + let json = db.execute(QUERY.into()).await.unwrap(); + let value: serde_json::Value = serde_json::from_str(&json).unwrap(); + let mut rows: Vec = value["results"] + .as_array() + .unwrap() + .iter() + .map(|r| r[0].as_u64().unwrap() as usize) + .collect(); + rows.sort_unstable(); + rows +} + +fn adapter(db: &BrowserDb) -> IndexedDbBackend { + db.inner.borrow().idb.as_ref().unwrap().clone_handle() +} + +/// Patch one connection, or the prototype filtered by database name. +/// Restoration also removes the page-error observer. +struct Fault { + state: JsValue, + restore: Function, +} +impl Fault { + fn new(target: &JsValue, store: &str, mode: &str) -> Self { + let state = js_sys::Object::new(); + let restore = Function::new_with_args("target,name,mode,state", r#" + const descriptor = Object.getOwnPropertyDescriptor(target,'transaction'); + const original = target.transaction; + state.sent = 0; state.errors = 0; state.pageErrors = []; + const pageError = e => { state.pageErrors.push(e.message); e.preventDefault(); }; + globalThis.addEventListener('error',pageError); + Object.defineProperty(target,'transaction',{configurable:true,value:function(...args) { + const tx = original.apply(this,args); + if (args[0] !== name || args[1] !== 'readwrite') return tx; + state.sent++; + if (state.sent !== 1) return tx; + tx.addEventListener('error',() => state.errors++); + if (mode === 'hold') { + const setter = Object.getOwnPropertyDescriptor(IDBTransaction.prototype,'oncomplete').set; + Object.defineProperty(tx,'oncomplete',{set(callback) { + setter.call(tx,event => { state.resume = () => callback(event); }); + }}); + } + const objectStore = tx.objectStore; + tx.objectStore = function(...args) { + const s = objectStore.apply(this,args), put = s.put; + let queued = 0, last; + s.put = function(...args) { + if (mode === 'throw' && queued++ === 1) + throw new DOMException('injected queue failure','QuotaExceededError'); + // add() of existing keys yields real request errors. + const req = mode === 'errors' ? s.add(...args) : put.apply(this,args); + last = req; + if (mode === 'abort' || mode === 'delayed-abort') { + req.addEventListener('success',() => { + if (req !== last) return; + // No outstanding requests: abort event only. + tx.abort(); + }); + } + return req; + }; + return s; + }; + if (mode === 'delayed-abort') { + const setter = Object.getOwnPropertyDescriptor(IDBTransaction.prototype,'onabort').set; + Object.defineProperty(tx,'onabort',{set(callback) { + setter.call(tx,event => { state.resume = () => callback(event); }); + }}); + } + return tx; + }}); + return () => { + if (descriptor) Object.defineProperty(target,'transaction',descriptor); + else delete target.transaction; + globalThis.removeEventListener('error',pageError); + }; + "#).call4(&JsValue::NULL, target, &store.into(), &mode.into(), &state).unwrap().unchecked_into(); + Self { + state: state.into(), + restore, + } + } + fn for_db(db: &BrowserDb, mode: &str) -> Self { + let idb = adapter(db); + Self::new(&idb.db, &idb.store_name, mode) + } + fn number(&self, key: &str) -> f64 { + Reflect::get(&self.state, &key.into()) + .unwrap() + .as_f64() + .unwrap() + } + async fn resume(&self) { + let p: Promise = Function::new_with_args( + "s", + r#" + return new Promise((resolve,reject) => { + const end = Date.now()+1500; + function poll() { + if (s.resume) { s.resume(); resolve(); } + else if (Date.now()>end) reject('no held outcome'); + else setTimeout(poll,0); + } + poll(); + }); + "#, + ) + .call1(&JsValue::NULL, &self.state) + .unwrap() + .unchecked_into(); + JsFuture::from(p).await.unwrap(); + } + fn no_page_errors(&self) { + let errors: js_sys::Array = Reflect::get(&self.state, &"pageErrors".into()) + .unwrap() + .unchecked_into(); + assert_eq!(errors.length(), 0, "callbacks must not throw"); + } +} +impl Drop for Fault { + fn drop(&mut self) { + self.restore.call0(&JsValue::NULL).unwrap(); + } +} + +async fn reopen(n: &str, expected: Vec) { + let db = BrowserDb::open(n).await.expect("fresh reopen"); + assert_eq!(rows(&db).await, expected); + // v7 has no free pages: every page named by the header must exist. + let pages = adapter(&db).load_all_pages().await.unwrap(); + let header = crate::storage::FileHeader::from_bytes(&pages[&0]).unwrap(); + assert!((0..header.page_count).all(|id| pages.contains_key(&id))); + let bytes = db.export_graph().unwrap().to_vec(); + // Opt-in transport for the native-open verification documented in TEST_COVERAGE. + if option_env!("MINIGRAF_EXPORT_RECOVERY").is_some() { + // Emit the actual recovered export for the native-open verification run. + let array = Uint8Array::from(bytes.as_slice()); + Function::new_with_args( + "bytes,expected", + r#" + let text = ''; for (const b of bytes) text += String.fromCharCode(b); + console.log('MINIGRAF_RECOVERED_EXPORT ' + JSON.stringify({ + bytes: btoa(text), expected: JSON.parse(expected) + })); + "#, + ) + .call2( + &JsValue::NULL, + &array, + &serde_json::to_string(&expected).unwrap().into(), + ) + .unwrap(); + } + adapter(&db).db.close(); +} + +async fn refused(db: &BrowserDb) { + let before = rows(db).await; + let count = db.inner.borrow().fact_storage.current_tx_count(); + let bytes = db.export_graph().unwrap().to_vec(); + for _ in 0..2 { + code(db.execute(write(900, 901)).await, "STG-046"); + code(db.execute("(retract [[:e0 :n 0]])".into()).await, "STG-046"); + code(db.checkpoint().await, "STG-046"); + code( + db.import_graph(Uint8Array::new_with_length(0)).await, + "STG-046", + ); + } + assert_eq!(db.inner.borrow().fact_storage.current_tx_count(), count); + assert_eq!(rows(db).await, before); + assert_eq!(db.export_graph().unwrap().to_vec(), bytes); + db.execute("(rule [(number ?e ?n) [?e :n ?n]])".into()) + .await + .unwrap(); +} + +#[wasm_bindgen_test] +async fn adapter_abort_only_settles() { + let n = name(); + let idb = IndexedDbBackend::open(&n).await.unwrap(); + idb.write_pages(vec![(0, vec![1])]).await.unwrap(); + let before = idb.load_all_pages().await.unwrap(); + let fault = Fault::new(&idb.db, &n, "abort"); + let copy = idb.clone_handle(); + let p = future_to_promise(async move { + copy.write_pages(vec![(0, vec![2]), (1, vec![3])]) + .await + .map(|()| JsValue::UNDEFINED) + }); + let error = deadline(p) + .await + .expect_err("abort rejects before deadline"); + assert!(js_text(&error).contains("STG-048"), "{}", js_text(&error)); + assert!(js_text(&error).contains("IndexedDB write")); + assert!(js_text(&error).contains("AbortError")); + assert_eq!(fault.number("errors"), 0.0, "abort-only, no request errors"); + assert_eq!(idb.load_all_pages().await.unwrap(), before); + fault.no_page_errors(); + drop(fault); + idb.write_pages(vec![(1, vec![4])]) + .await + .expect("connection is recoverable"); + idb.db.close(); +} + +#[wasm_bindgen_test] +async fn adapter_queue_throw_is_atomic() { + let n = name(); + let idb = IndexedDbBackend::open(&n).await.unwrap(); + idb.write_pages(vec![(0, vec![1]), (9, vec![9])]) + .await + .unwrap(); + let before = idb.load_all_pages().await.unwrap(); + let fault = Fault::new(&idb.db, &n, "throw"); + let error = idb + .write_pages(vec![(0, vec![2]), (1, vec![3])]) + .await + .unwrap_err(); + assert_eq!( + idb.load_all_pages().await.unwrap(), + before, + "queued puts must roll back" + ); + assert!(js_text(&error).contains("STG-048")); + assert!(js_text(&error).contains("QuotaExceededError")); + fault.no_page_errors(); + idb.db.close(); +} + +#[wasm_bindgen_test] +async fn adapter_multiple_request_errors_settle_once() { + let n = name(); + let idb = IndexedDbBackend::open(&n).await.unwrap(); + let pages = vec![(0, vec![1]), (1, vec![2]), (2, vec![3])]; + idb.write_pages(pages.clone()).await.unwrap(); + let before = idb.load_all_pages().await.unwrap(); + let fault = Fault::new(&idb.db, &n, "errors"); + code(idb.write_pages(pages).await, "STG-048"); + assert_eq!(idb.load_all_pages().await.unwrap(), before); + assert!(fault.number("errors") >= 2.0); + fault.no_page_errors(); + idb.db.close(); +} + +#[wasm_bindgen_test] +async fn multipage_failed_write_refuses_successors() { + let n = name(); + let db = BrowserDb::open(&n).await.unwrap(); + db.execute(write(0, 2)).await.unwrap(); + let before = adapter(&db).load_all_pages().await.unwrap(); + let fault = Fault::for_db(&db, "throw"); + let failed = db.execute(write(2, 402)).await; + assert!( + adapter(&db).load_all_pages().await.unwrap() == before, + "multi-page failure must leave every durable byte unchanged" + ); + code(failed, "STG-048"); + assert_eq!(rows(&db).await.len(), 402); + assert!( + db.inner + .borrow() + .pfs + .with_backend(|b| (0..b.page_count_raw().unwrap()).any(|id| !before.contains_key(&id))), + "write appended pages" + ); + refused(&db).await; + assert_eq!(fault.number("sent"), 1.0); + assert_eq!(adapter(&db).load_all_pages().await.unwrap(), before); + drop(fault); + adapter(&db).db.close(); + reopen(&n, vec![0, 1]).await; +} + +#[wasm_bindgen_test] +async fn checkpoint_and_smaller_import_fail_atomically() { + for operation in ["checkpoint", "import"] { + let n = name(); + let db = BrowserDb::open(&n).await.unwrap(); + db.execute(write(0, 400)).await.unwrap(); + let before = adapter(&db).load_all_pages().await.unwrap(); + let fault = Fault::for_db(&db, "abort"); + let p = match operation { + "checkpoint" => { + // Real dirty bytes of its own, without another flush. + db.inner.borrow_mut().pfs.with_backend_mut(|b| { + let page = b.read_page(0).unwrap(); + b.write_page(0, &page).unwrap(); + }); + checkpoint(&db) + } + _ => import(&db, empty_image()), + }; + code(deadline(p).await, "STG-048"); + assert_eq!( + rows(&db).await.len(), + match operation { + "import" => 0, + _ => 400, + } + ); + refused(&db).await; + assert_eq!(fault.number("sent"), 1.0); + assert_eq!(adapter(&db).load_all_pages().await.unwrap(), before); + drop(fault); + adapter(&db).db.close(); + reopen(&n, (0..400).collect()).await; + } +} + +#[wasm_bindgen_test] +async fn nonempty_smaller_import_fails_atomically() { + let source = BrowserDb::open_in_memory().unwrap(); + source.execute(write(500, 502)).await.unwrap(); + let image = source.export_graph().unwrap(); + drop(source); + + let n = name(); + let db = BrowserDb::open(&n).await.unwrap(); + db.execute(write(0, 400)).await.unwrap(); + assert!(image.length() < db.export_graph().unwrap().length()); + let before = adapter(&db).load_all_pages().await.unwrap(); + let fault = Fault::for_db(&db, "abort"); + code(deadline(import(&db, image)).await, "STG-048"); + assert_eq!(rows(&db).await, vec![500, 501]); + refused(&db).await; + assert_eq!(fault.number("sent"), 1.0); + assert_eq!(adapter(&db).load_all_pages().await.unwrap(), before); + fault.no_page_errors(); + drop(fault); + adapter(&db).db.close(); + reopen(&n, (0..400).collect()).await; +} + +#[wasm_bindgen_test] +async fn preparation_error_keeps_code_and_fails_handle() { + for operation in ["execute", "checkpoint"] { + let n = name(); + let db = BrowserDb::open(&n).await.unwrap(); + db.execute(write(0, 2)).await.unwrap(); + let fault = Fault::for_db(&db, "hold"); + db.inner.borrow_mut().pfs.with_backend_mut(|b| { + b.mark_dirty_for_test(999_999); + }); + let p = match operation { + "checkpoint" => checkpoint(&db), + _ => execute(&db, write(2, 3)), + }; + code(deadline(p).await, "INT-052"); + refused(&db).await; + assert_eq!(fault.number("sent"), 0.0); + adapter(&db).db.close(); + reopen(&n, vec![0, 1]).await; + } +} + +#[wasm_bindgen_test] +async fn overlapping_failure_never_submits_successor() { + for pair in [ + "execute-execute", + "execute-import", + "import-execute", + "execute-checkpoint", + ] { + let n = name(); + let db = BrowserDb::open(&n).await.unwrap(); + db.execute(write(0, 2)).await.unwrap(); + let before = adapter(&db).load_all_pages().await.unwrap(); + let fault = Fault::for_db(&db, "delayed-abort"); + let first = if pair.starts_with("import") { + import(&db, empty_image()) + } else { + execute(&db, write(2, 402)) + }; + tick().await; + let second = if pair.ends_with("import") { + import(&db, empty_image()) + } else if pair.ends_with("checkpoint") { + checkpoint(&db) + } else { + execute(&db, write(500, 501)) + }; + tick().await; + assert_eq!(fault.number("sent"), 1.0, "successor waits"); + assert_eq!( + rows(&db).await.len(), + match pair { + "execute-import" => 0, + "import-execute" => 1, + "execute-checkpoint" => 402, + _ => 403, + } + ); + fault.resume().await; + code(deadline(first).await, "STG-048"); + code(deadline(second).await, "STG-046"); + refused(&db).await; + assert_eq!(fault.number("sent"), 1.0); + assert_eq!(adapter(&db).load_all_pages().await.unwrap(), before); + drop(fault); + adapter(&db).db.close(); + reopen(&n, vec![0, 1]).await; + } +} + +#[wasm_bindgen_test] +async fn successful_checkpoint_boundary_and_mixed_overlap() { + let n = name(); + let db = BrowserDb::open(&n).await.unwrap(); + db.execute(write(0, 2)).await.unwrap(); + let fault = Fault::for_db(&db, "hold"); + let first = execute(&db, write(2, 402)); + tick().await; + let boundary = checkpoint(&db); + let observed = js_sys::Object::new(); + Function::new_with_args("p,s", "p.then(() => s.done=true)") + .call2(&JsValue::NULL, &boundary, &observed) + .unwrap(); + tick().await; + assert!( + !Reflect::get(&observed, &"done".into()).unwrap().is_truthy(), + "empty checkpoint waits" + ); + let replace = import(&db, empty_image()); + tick().await; + let write = execute(&db, write(600, 602)); + let retract = execute(&db, "(retract [[:e600 :n 600]])".into()); + tick().await; + assert_eq!(fault.number("sent"), 1.0); + fault.resume().await; + for p in [first, boundary, replace, write, retract] { + deadline(p).await.unwrap(); + } + assert_eq!(rows(&db).await, vec![601]); + drop(fault); + adapter(&db).db.close(); + reopen(&n, vec![601]).await; +} + +#[wasm_bindgen_test] +async fn fresh_open_after_rejected_write_is_read_only_and_writable() { + let n = name(); + let db = BrowserDb::open(&n).await.unwrap(); + db.execute(write(0, 2)).await.unwrap(); + let before = adapter(&db).load_all_pages().await.unwrap(); + let fault = Fault::for_db(&db, "abort"); + code(deadline(execute(&db, write(2, 402))).await, "STG-048"); + drop(fault); + adapter(&db).db.close(); + let prototype = Reflect::get(&js_sys::global(), &"IDBDatabase".into()).unwrap(); + let prototype = Reflect::get(&prototype, &"prototype".into()).unwrap(); + let fault = Fault::new(&prototype, &n, "hold"); + let fresh = BrowserDb::open(&n).await.unwrap(); + assert_eq!(fault.number("sent"), 0.0, "open must not write back"); + assert_eq!(adapter(&fresh).load_all_pages().await.unwrap(), before); + assert_eq!(rows(&fresh).await, vec![0, 1]); + drop(fault); + fresh.execute(write(9, 10)).await.unwrap(); + adapter(&fresh).db.close(); + reopen(&n, vec![0, 1, 9]).await; +} + +#[wasm_bindgen_test] +async fn closed_connection_failure_preserves_memory_and_refuses_writes() { + let n = name(); + let db = BrowserDb::open(&n).await.unwrap(); + db.execute(write(0, 2)).await.unwrap(); + adapter(&db).db.close(); + let error = db.execute(write(2, 3)).await.unwrap_err(); + assert!(js_text(&error).contains("InvalidStateError")); + code::<()>(Err(error), "STG-048"); + assert_eq!(rows(&db).await, vec![0, 1, 2]); + refused(&db).await; + reopen(&n, vec![0, 1]).await; +} + +#[wasm_bindgen_test] +async fn checkpoint_does_not_wait_for_later_writes() { + let n = name(); + let db = BrowserDb::open(&n).await.unwrap(); + let first_fault = Fault::for_db(&db, "hold"); + let first = execute(&db, write(0, 2)); + tick().await; + let boundary = checkpoint(&db); + tick().await; + // Restore admission of transactions, retaining the first held callback. + first_fault.restore.call0(&JsValue::NULL).unwrap(); + let later_fault = Fault::for_db(&db, "hold"); + let later = execute(&db, write(2, 3)); + tick().await; + first_fault.resume().await; + deadline(first).await.unwrap(); + deadline(boundary) + .await + .expect("boundary excludes later pending flush"); + later_fault.resume().await; + deadline(later).await.unwrap(); + drop(later_fault); + drop(first_fault); + adapter(&db).db.close(); + reopen(&n, vec![0, 1, 2]).await; +} + +#[wasm_bindgen_test] +async fn preparation_failure_preserves_earlier_successful_prefix() { + let n = name(); + let db = BrowserDb::open(&n).await.unwrap(); + let fault = Fault::for_db(&db, "hold"); + let first = execute(&db, write(0, 2)); + tick().await; + db.inner.borrow_mut().pfs.with_backend_mut(|b| { + b.mark_dirty_for_test(999_999); + }); + let broken = execute(&db, write(2, 3)); + let observed = js_sys::Object::new(); + Function::new_with_args("p,s", "p.catch(() => s.done=true)") + .call2(&JsValue::NULL, &broken, &observed) + .unwrap(); + tick().await; + assert!( + !Reflect::get(&observed, &"done".into()).unwrap().is_truthy(), + "even preparation failure waits for earlier work" + ); + code(db.checkpoint().await, "STG-046"); + fault.resume().await; + deadline(first).await.unwrap(); + code(deadline(broken).await, "INT-052"); + assert_eq!(fault.number("sent"), 1.0); + assert!( + db.inner.borrow().flush_tail.is_none(), + "settled barriers released" + ); + drop(fault); + adapter(&db).db.close(); + reopen(&n, vec![0, 1]).await; +} + +#[wasm_bindgen_test] +async fn validation_errors_do_not_fail_handle_or_retain_flushes() { + let n = name(); + let db = BrowserDb::open(&n).await.unwrap(); + assert!(db.execute("(transact [[:bad :n]])".into()).await.is_err()); + assert!( + db.import_graph(Uint8Array::new_with_length(1)) + .await + .is_err() + ); + for i in 0..20 { + db.execute(write(i, i + 1)).await.unwrap(); + db.checkpoint().await.unwrap(); + assert!(db.inner.borrow().failed_flush.is_none()); + assert!( + db.inner.borrow().flush_tail.is_none(), + "no settled history retained" + ); + } + adapter(&db).db.close(); + reopen(&n, (0..20).collect()).await; +} diff --git a/src/browser/indexeddb.rs b/src/browser/indexeddb.rs index 8ca8a0957a..032881f0ea 100644 --- a/src/browser/indexeddb.rs +++ b/src/browser/indexeddb.rs @@ -4,7 +4,9 @@ //! Called directly by `BrowserDb` after synchronous `PersistentFactStorage::save()`. use js_sys::{Array, Promise, Uint8Array}; +use std::cell::Cell; use std::collections::HashMap; +use std::rc::Rc; use wasm_bindgen::JsCast; use wasm_bindgen::closure::Closure; use wasm_bindgen::prelude::*; @@ -34,25 +36,104 @@ fn request_to_promise(request: &IdbRequest) -> Promise { }) } -/// Converts an `IdbTransaction` completion into a JS `Promise`. -fn transaction_to_promise(tx: &IdbTransaction) -> Promise { - let tx = tx.clone(); - Promise::new(&mut |resolve, reject| { - let on_complete: Closure = - Closure::once(move |_: web_sys::Event| { - resolve.call0(&JsValue::NULL).ok(); - }); - let on_error: Closure = - Closure::once(move |_: web_sys::Event| { - reject - .call1(&JsValue::NULL, &JsValue::from_str("IdbTransaction failed")) - .ok(); - }); - tx.set_oncomplete(Some(on_complete.as_ref().unchecked_ref())); - tx.set_onerror(Some(on_error.as_ref().unchecked_ref())); - on_complete.forget(); - on_error.forget(); - }) +/// Own the transaction's listeners until settlement. Request errors bubble to +/// the transaction, potentially more than once; all three events share one +/// idempotent settlement flag. Dropping this guard detaches and frees them. +struct TransactionWait { + tx: IdbTransaction, + promise: Promise, + _complete: Closure, + _error: Closure, + _abort: Closure, +} + +impl TransactionWait { + fn new(tx: &IdbTransaction) -> Self { + let settled = Rc::new(Cell::new(false)); + let mut listeners = None; + let promise = Promise::new(&mut |resolve, reject| { + let done = settled.clone(); + let complete: Closure = + Closure::new(move |_: web_sys::Event| { + if !done.replace(true) { + let _ = resolve.call0(&JsValue::NULL); + } + }); + let done = settled.clone(); + let failed_tx = tx.clone(); + let reject_error = reject.clone(); + let error: Closure = + Closure::new(move |event: web_sys::Event| { + if !done.replace(true) { + // On a bubbling request error tx.error may not yet be + // set. Preserve the request's original exception name. + let exception = event + .target() + .and_then(|t| t.dyn_into::().ok()) + .and_then(|r| r.error().ok().flatten()) + .or_else(|| failed_tx.error()); + let reason = transaction_error(exception); + // Never allow a prevented request error to commit a + // prefix of this batch. + let _ = failed_tx.abort(); + let _ = reject_error.call1(&JsValue::NULL, &reason); + } + }); + let done = settled.clone(); + let aborted_tx = tx.clone(); + let abort: Closure = + Closure::new(move |_: web_sys::Event| { + if !done.replace(true) { + let reason = transaction_error(aborted_tx.error()); + let _ = reject.call1(&JsValue::NULL, &reason); + } + }); + tx.set_oncomplete(Some(complete.as_ref().unchecked_ref())); + tx.set_onerror(Some(error.as_ref().unchecked_ref())); + tx.set_onabort(Some(abort.as_ref().unchecked_ref())); + listeners = Some((complete, error, abort)); + }); + // Promise::new invokes its executor synchronously. + let (complete, error, abort) = match listeners { + Some(listeners) => listeners, + None => unreachable!("Promise executor runs synchronously"), + }; + Self { + tx: tx.clone(), + promise, + _complete: complete, + _error: error, + _abort: abort, + } + } +} + +impl Drop for TransactionWait { + fn drop(&mut self) { + self.tx.set_oncomplete(None); + self.tx.set_onerror(None); + self.tx.set_onabort(None); + } +} + +fn write_error(error: JsValue) -> JsValue { + let name = js_sys::Reflect::get(&error, &"name".into()) + .ok() + .and_then(|n| n.as_string()) + .unwrap_or_else(|| error.as_string().unwrap_or_else(|| format!("{error:?}"))); + super::to_js_error(crate::error::err_coded!( + crate::error::ErrorCode::Stg048, + "IndexedDB write", + name + )) +} + +fn transaction_error(exception: Option) -> JsValue { + write_error(exception.map(JsValue::from).unwrap_or_else(|| { + // Explicit abort() has no transaction.error, but its DOM outcome is + // still AbortError. + JsValue::from_str("AbortError") + })) } /// Async wrapper around a browser IndexedDB database. @@ -156,20 +237,26 @@ impl IndexedDbBackend { } let tx = self .db - .transaction_with_str_and_mode(&self.store_name, IdbTransactionMode::Readwrite)?; - let store = tx.object_store(&self.store_name)?; - - for (page_id, data) in &pages { - let key = JsValue::from_f64(*page_id as f64); - let arr = Uint8Array::from(data.as_slice()); - store.put_with_key(&arr, &key)?; + .transaction_with_str_and_mode(&self.store_name, IdbTransactionMode::Readwrite) + .map_err(write_error)?; + let wait = TransactionWait::new(&tx); + let queued = (|| { + let store = tx.object_store(&self.store_name)?; + for (page_id, data) in &pages { + let key = JsValue::from_f64(*page_id as f64); + let arr = Uint8Array::from(data.as_slice()); + store.put_with_key(&arr, &key)?; + } + Ok::<(), JsValue>(()) + })(); + if let Err(error) = queued { + // A synchronous throw does not abort IndexedDB automatically. + // Roll back every earlier put, then observe settlement. + let _ = tx.abort(); + let _ = JsFuture::from(wait.promise.clone()).await; + return Err(write_error(error)); } - - // Wait for the transaction to commit. The IDB transaction commits - // automatically once all put requests have been processed and no - // new requests are made. We wait here to ensure durability before - // returning to the caller. - JsFuture::from(transaction_to_promise(&tx)).await?; + JsFuture::from(wait.promise.clone()).await?; Ok(()) } } diff --git a/src/browser/mod.rs b/src/browser/mod.rs index 3f94178745..88c3274142 100644 --- a/src/browser/mod.rs +++ b/src/browser/mod.rs @@ -6,11 +6,14 @@ /// Synchronous in-memory page buffer with dirty-page tracking. pub mod buffer; +#[cfg(test)] +mod flush_tests; /// Async IndexedDB backend for browser WASM persistence. pub mod indexeddb; use crate::browser::buffer::BrowserBufferBackend; use crate::browser::indexeddb::IndexedDbBackend; +use crate::error::{ErrorCode, err_coded}; use crate::graph::FactStorage; use crate::query::datalog::executor::{DatalogExecutor, QueryResult}; use crate::query::datalog::functions::FunctionRegistry; @@ -31,11 +34,39 @@ struct BrowserDbInner { pfs: PersistentFactStorage, /// `None` for in-memory databases (no IDB backing). idb: Option, + /// First failed flush, independent of the storage replaced by import. + failed_flush: Option, + /// Only the last outstanding barrier; settled batches are released. + flush_tail: Option<(u64, js_sys::Promise)>, + flush_sequence: u64, } +impl BrowserDbInner { + fn refuse_failed_flush(&self) -> Result<(), JsValue> { + if self.failed_flush.is_some() { + return Err(to_js_error(err_coded!(ErrorCode::Stg046))); + } + Ok(()) + } + + fn fail_flush(&mut self, sequence: u64) { + self.failed_flush = Some(self.failed_flush.map_or(sequence, |old| old.min(sequence))); + } +} + +/// Memory was applied; a preparation error keeps its engine code and fails +/// the handle, unlike validation errors before application. +struct FlushWork(Result)>, JsValue>); + /// Browser-only Minigraf database handle backed by IndexedDB. /// -/// All public methods return `Promise`s. Use `await` in JavaScript. +/// Writes, checkpoint and open return `Promise`s. Use `await` in JavaScript. +/// +/// IndexedDB flushes are atomic and ordered. A failed flush rejects with +/// `[STG-048]`; page-preparation errors keep their engine code. Later writes, +/// checkpoints and imports reject with `[STG-046]`. Reads, rules and export +/// still work, including rejected work already applied in memory. Discard the +/// failed handle and reopen to recover the successful prefix before failure. /// /// **Not compatible with Node.js.** Use `@minigraf/node` for server-side use. #[wasm_bindgen] @@ -64,6 +95,9 @@ impl BrowserDb { functions: Arc::new(RwLock::new(FunctionRegistry::with_builtins())), pfs, idb: None, + failed_flush: None, + flush_tail: None, + flush_sequence: 0, })), }) } @@ -89,12 +123,20 @@ impl BrowserDb { functions: Arc::new(RwLock::new(FunctionRegistry::with_builtins())), pfs, idb: Some(idb), + failed_flush: None, + flush_tail: None, + flush_sequence: 0, })), }) } /// Execute a Datalog command string and return a JSON-encoded result. /// + /// In IndexedDB mode, a failed flush rejects with `[STG-048]` and later + /// transact/retract calls reject with `[STG-046]` without changing memory. + /// Queries and rules remain available; discard the handle and reopen to + /// recover. Page-preparation failures retain their original engine code. + /// /// Returns a `Promise` in JavaScript. The JSON shape is: /// - Query: `{"variables": [...], "results": [[...], ...]}` /// - Transact: `{"transacted": }` @@ -121,6 +163,7 @@ impl BrowserDb { return Ok(query_result_to_json(result)); } + self.inner.borrow().refuse_failed_flush()?; match cmd { DatalogCommand::Transact(tx) => { let facts = @@ -139,21 +182,24 @@ impl BrowserDb { /// Flush all dirty pages to IndexedDB. /// - /// Write-through means individual `execute()` calls already flush dirty pages, - /// so `checkpoint()` is only needed after `import_graph()` or explicit bulk ops. - /// No-op for in-memory databases. + /// Waits for every IndexedDB write applied before this call, even if it + /// has no pages of its own. Later writes are outside this boundary. Its + /// own flush failure is `[STG-048]`; an earlier failed flush is `[STG-046]`. + /// Discard the handle and reopen to recover. With no earlier work or dirty + /// pages it resolves immediately. No-op for in-memory databases. pub async fn checkpoint(&self) -> Result<(), JsValue> { - let (dirty_pages, has_idb) = { + let work = { let mut inner = self.inner.borrow_mut(); - inner.pfs.save().map_err(to_js_error)?; - let pages = take_dirty_pages(&mut inner.pfs)?; - (pages, inner.idb.is_some()) + inner.refuse_failed_flush()?; + FlushWork( + inner + .pfs + .save() + .map_err(to_js_error) + .and_then(|()| take_dirty_pages(&mut inner.pfs)), + ) }; - - if has_idb && !dirty_pages.is_empty() { - let idb = self.inner.borrow().idb.as_ref().unwrap().clone_handle(); - idb.write_pages(dirty_pages).await?; - } + wasm_bindgen_futures::JsFuture::from(self.flush(work)).await?; Ok(()) } @@ -161,6 +207,8 @@ impl BrowserDb { /// /// The blob is byte-for-bit compatible with native `.graph` files opened by /// `Minigraf::open()`. Pages are always in ascending `page_id` order. + /// On a failed IndexedDB handle this includes rejected work already applied + /// in memory; export does not acknowledge durability. /// /// Call `checkpoint()` on native before importing a file here to ensure /// no WAL entries are missing from the main file. @@ -188,8 +236,12 @@ impl BrowserDb { /// The blob must be a checkpointed native `.graph` file (no pending WAL sidecar). /// All existing data is overwritten. After import, the new data is immediately /// queryable and all dirty pages are flushed to IndexedDB. + /// A flush failure is `[STG-048]`: memory retains the imported graph, while + /// IndexedDB retains the previous graph. Later durable work is `[STG-046]`, + /// including imports (no live swap), until the handle is discarded and reopened. #[wasm_bindgen(js_name = importGraph)] pub async fn import_graph(&self, data: js_sys::Uint8Array) -> Result<(), JsValue> { + self.inner.borrow().refuse_failed_flush()?; let bytes = data.to_vec(); if bytes.len() % crate::storage::PAGE_SIZE != 0 { return Err(JsValue::from_str( @@ -203,32 +255,87 @@ impl BrowserDb { } // ── Sync section ────────────────────────────────────────────────────────── - let (dirty_pages, has_idb) = { + let work = { let mut inner = self.inner.borrow_mut(); let buffer = BrowserBufferBackend::load_pages_all_dirty(pages); // Page cache capacity 0 — see comment in `open_in_memory` above. - let mut new_pfs = PersistentFactStorage::new(buffer, 0).map_err(to_js_error)?; + let new_pfs = PersistentFactStorage::new(buffer, 0).map_err(to_js_error)?; let new_fact_storage = new_pfs.storage().clone(); - // Drain dirty set and collect owned page bytes before swapping inner. - let dirty_pages = take_dirty_pages(&mut new_pfs)?; - + // Preserve the memory contract even if flush preparation fails. + // The failed-flush state belongs to the handle, not this new pfs. inner.pfs = new_pfs; inner.fact_storage = new_fact_storage; - (dirty_pages, inner.idb.is_some()) + FlushWork(take_dirty_pages(&mut inner.pfs)) }; // ── Borrow dropped ──────────────────────────────────────────────────────── - if has_idb && !dirty_pages.is_empty() { - let idb = self.inner.borrow().idb.as_ref().unwrap().clone_handle(); - idb.write_pages(dirty_pages).await?; - } + wasm_bindgen_futures::JsFuture::from(self.flush(work)).await?; Ok(()) } } impl BrowserDb { + /// Reserve the durability boundary before deferring its work. Barriers + /// always resolve; the operation itself reports any error, so an internal + /// predecessor cannot cause an unhandled promise rejection. + fn flush(&self, work: FlushWork) -> js_sys::Promise { + let mut inner = self.inner.borrow_mut(); + let Some(idb) = inner.idb.as_ref().map(IndexedDbBackend::clone_handle) else { + return match work.0 { + Ok(_) => js_sys::Promise::resolve(&JsValue::UNDEFINED), + Err(error) => js_sys::Promise::reject(&error), + }; + }; + inner.flush_sequence += 1; + let sequence = inner.flush_sequence; + if work.0.is_err() { + // Fail admission now, but let the earlier successful prefix finish. + inner.fail_flush(sequence); + } + let previous = inner.flush_tail.take(); + if previous.is_none() && work.0.as_ref().is_ok_and(Vec::is_empty) { + return js_sys::Promise::resolve(&JsValue::UNDEFINED); + } + let mut release = None; + let barrier = js_sys::Promise::new(&mut |resolve, _| release = Some(resolve)); + inner.flush_tail = Some((sequence, barrier)); + let db = self.inner.clone(); + wasm_bindgen_futures::future_to_promise(async move { + if let Some((_, previous)) = previous { + let _ = wasm_bindgen_futures::JsFuture::from(previous).await; + } + let result = async { + if db + .borrow() + .failed_flush + .is_some_and(|failed| failed < sequence) + { + return Err(to_js_error(err_coded!(ErrorCode::Stg046))); + } + let pages = work.0?; + idb.write_pages(pages) + .await + .inspect_err(|_| db.borrow_mut().fail_flush(sequence)) + } + .await; + let mut inner = db.borrow_mut(); + if inner + .flush_tail + .as_ref() + .is_some_and(|(last, _)| *last == sequence) + { + inner.flush_tail.take(); + } + drop(inner); + if let Some(release) = release { + let _ = release.call0(&JsValue::NULL); + } + result.map(|()| JsValue::UNDEFINED) + }) + } + /// Apply a batch of pre-materialized facts to the in-memory store and /// flush dirty pages to IndexedDB (if present). /// @@ -243,7 +350,7 @@ impl BrowserDb { use crate::graph::types::tx_id_now; // ── Sync section: hold borrow, do ALL sync work, collect owned data ── - let (dirty_pages, result_json) = { + let (work, result_json) = { let mut inner = self.inner.borrow_mut(); let tx_count = inner.fact_storage.allocate_tx_count(); @@ -261,17 +368,16 @@ impl BrowserDb { }) .collect(); - // One batch, so no query sees part of the transaction (#554). - inner - .fact_storage - .load_facts(stamped.iter().cloned()) - .map_err(to_js_error)?; - - inner.pfs.mark_dirty(); - inner.pfs.save().map_err(to_js_error)?; - - // Collect dirty pages as owned Vec<(u64, Vec)> — no borrows escape - let dirty_pages = take_dirty_pages(&mut inner.pfs)?; + let work = FlushWork((|| { + // One batch, so no query sees part of the transaction (#554). + inner + .fact_storage + .load_facts(stamped) + .map_err(to_js_error)?; + inner.pfs.mark_dirty(); + inner.pfs.save().map_err(to_js_error)?; + take_dirty_pages(&mut inner.pfs) + })()); let json = if is_retract { format!(r#"{{"retracted":{}}}"#, tx_id) @@ -279,18 +385,12 @@ impl BrowserDb { format!(r#"{{"transacted":{}}}"#, tx_id) }; - (dirty_pages, json) + (work, json) }; // ── Borrow dropped here ─────────────────────────────────────────────── // ── Async section: flush to IDB (no RefCell borrow held) ───────────── - if !dirty_pages.is_empty() { - let has_idb = self.inner.borrow().idb.is_some(); - if has_idb { - let idb = self.inner.borrow().idb.as_ref().unwrap().clone_handle(); - idb.write_pages(dirty_pages).await?; - } - } + wasm_bindgen_futures::JsFuture::from(self.flush(work)).await?; Ok(result_json) } diff --git a/src/error.rs b/src/error.rs index bb1f086f65..c2db1dc677 100644 --- a/src/error.rs +++ b/src/error.rs @@ -165,6 +165,8 @@ pub(crate) enum ErrorCode { Stg026, Stg027, Stg045, + Stg046, + Stg048, Wal001, Wal002, Wal003, @@ -952,6 +954,18 @@ pub(crate) const REGISTRY: &[(ErrorCode, &str, &str, ErrorCategory)] = &[ "File is {} bytes, shorter than one page, and is not a new Minigraf database", ErrorCategory::Storage, ), + ( + ErrorCode::Stg046, + "STG-046", + "an earlier checkpoint or IndexedDB flush failed on this handle and is not retried; reopen the database", + ErrorCategory::Storage, + ), + ( + ErrorCode::Stg048, + "STG-048", + "browser storage operation failed: {} ({})", + ErrorCategory::Storage, + ), ( ErrorCode::Wal001, "WAL-001", @@ -1774,6 +1788,8 @@ mod tests { | ErrorCode::Stg026 | ErrorCode::Stg027 | ErrorCode::Stg045 + | ErrorCode::Stg046 + | ErrorCode::Stg048 | ErrorCode::Wal001 | ErrorCode::Wal002 | ErrorCode::Wal003 @@ -1968,6 +1984,8 @@ mod tests { ErrorCode::Stg026, ErrorCode::Stg027, ErrorCode::Stg045, + ErrorCode::Stg046, + ErrorCode::Stg048, ErrorCode::Wal001, ErrorCode::Wal002, ErrorCode::Wal003,