Skip to content

Self-evolving Context Database for AI Agents. Unify Agent Memory, Knowledge RAG and Skills.

feat(ragfs): add transactional SQLite path locks (#6679)

zhanglistar15cf3ae28bed
diff --git a/crates/ov_cli/tests/api_key_rotation.rs b/crates/ov_cli/tests/api_key_rotation.rs
index e6341a784..82be9ccbf 100644
--- a/crates/ov_cli/tests/api_key_rotation.rs
+++ b/crates/ov_cli/tests/api_key_rotation.rs
@@ -14,8 +14,18 @@ const OLD_KEY: &str = "YWNtZQ.YWxpY2U.b2xkLXNlY3JldA";
const NEW_KEY: &str = "YWNtZQ.YWxpY2U.bmV3LXNlY3JldA";
fn run(dir: &Path, args: &[&str]) -> Output {
+ let home = dir.join("home");
+ let settings_dir = home.join(".openviking");
+ fs::create_dir_all(&settings_dir).unwrap();
+ fs::write(
+ settings_dir.join("ovcli.settings.conf"),
+ json!({"language": "en"}).to_string(),
+ )
+ .unwrap();
Command::new(env!("CARGO_BIN_EXE_ov"))
.current_dir(dir)
+ .env("HOME", &home)
+ .env("USERPROFILE", &home)
.env("OPENVIKING_CLI_CONFIG_FILE", "selected.json")
.env("OPENVIKING_LANG", "en")
.env("NO_COLOR", "1")
@@ -48,6 +58,7 @@ fn serve(
Err(error) => panic!("{error}"),
}
};
+ stream.set_nonblocking(false).unwrap();
stream
.set_read_timeout(Some(Duration::from_secs(5)))
.unwrap();
diff --git a/crates/ov_cli/tests/config_override.rs b/crates/ov_cli/tests/config_override.rs
index 125b5483d..0b9358278 100644
--- a/crates/ov_cli/tests/config_override.rs
+++ b/crates/ov_cli/tests/config_override.rs
@@ -6,8 +6,18 @@ use std::{
};
fn run(dir: &std::path::Path, selected: &str, args: &[&str]) -> Output {
+ let home = dir.join("home");
+ let settings_dir = home.join(".openviking");
+ fs::create_dir_all(&settings_dir).unwrap();
+ fs::write(
+ settings_dir.join("ovcli.settings.conf"),
+ json!({"language": "en"}).to_string(),
+ )
+ .unwrap();
Command::new(env!("CARGO_BIN_EXE_ov"))
.current_dir(dir)
+ .env("HOME", &home)
+ .env("USERPROFILE", &home)
.env("OPENVIKING_CLI_CONFIG_FILE", selected)
.env("OPENVIKING_LANG", "en")
.env("NO_COLOR", "1")
diff --git a/crates/ragfs-python/src/lib.rs b/crates/ragfs-python/src/lib.rs
index 129524107..777a1e9c2 100644
--- a/crates/ragfs-python/src/lib.rs
+++ b/crates/ragfs-python/src/lib.rs
@@ -447,7 +447,31 @@ fn pathlock_config_from_canonical_ov_conf(
.and_then(|storage| storage.get("agfs"))
.and_then(|agfs| agfs.get("pathlock"));
match pathlock {
- Some(pathlock) => pathlock_config_from_value(pathlock, service_name),
+ Some(pathlock) => {
+ let mut pathlock = pathlock.clone();
+ if pathlock.get("provider").and_then(serde_json::Value::as_str) == Some("sqlite")
+ && pathlock
+ .get("sqlite_path")
+ .is_none_or(serde_json::Value::is_null)
+ {
+ let workspace = json
+ .get("storage")
+ .and_then(|storage| storage.get("workspace"))
+ .and_then(serde_json::Value::as_str)
+ .filter(|workspace| !workspace.is_empty())
+ .ok_or_else(|| {
+ "storage.workspace is required for the default SQLite lock database"
+ .to_string()
+ })?;
+ // The workspace may not exist yet. Resolve relative paths against
+ // the process working directory without requiring existing parents.
+ let database = std::path::absolute(workspace)
+ .map_err(|error| format!("failed to resolve storage.workspace: {error}"))?
+ .join("_system/pathlock/pathlock.db");
+ pathlock["sqlite_path"] = serde_json::json!(database);
+ }
+ pathlock_config_from_value(&pathlock, service_name)
+ }
None => Ok(PathLockConfig::default()),
}
}
@@ -460,7 +484,12 @@ fn pathlock_config_from_value(
let pathlock = value
.as_object()
.ok_or_else(|| "pathlock config must be an object".to_string())?;
- const FIELDS: &[&str] = &["provider", "lock_timeout_secs", "lock_expire_secs"];
+ const FIELDS: &[&str] = &[
+ "provider",
+ "sqlite_path",
+ "lock_timeout_secs",
+ "lock_expire_secs",
+ ];
if let Some(field) = pathlock
.keys()
.find(|field| !FIELDS.contains(&field.as_str()))
@@ -469,12 +498,25 @@ fn pathlock_config_from_value(
}
let provider = string_field(pathlock, "provider", "filesystem")?;
- if !matches!(provider.as_str(), "filesystem" | "memory" | "cache") {
+ if !matches!(provider.as_str(), "filesystem" | "memory" | "sqlite" | "cache") {
return Err(format!(
- "unsupported pathlock.provider: {provider}; expected filesystem, memory, or cache"
+ "unsupported pathlock.provider: {provider}; expected filesystem, memory, sqlite, or cache"
));
}
- let pathlock_service_name = (provider == "cache").then(|| service_name.to_string());
+ let pathlock_service_name =
+ matches!(provider.as_str(), "cache" | "sqlite").then(|| service_name.to_string());
+ let sqlite_path = match pathlock.get("sqlite_path") {
+ None | Some(serde_json::Value::Null) => None,
+ Some(serde_json::Value::String(path)) => Some(path.clone()),
+ _ => return Err("pathlock.sqlite_path must be a string".to_string()),
+ };
+ if provider == "sqlite"
+ && !sqlite_path
+ .as_deref()
+ .is_some_and(|path| std::path::Path::new(path).is_absolute())
+ {
+ return Err("pathlock.sqlite_path must be an absolute local file path".to_string());
+ }
let lock_timeout_secs = f64_field(pathlock, "lock_timeout_secs", 0.0)?;
if !lock_timeout_secs.is_finite() || lock_timeout_secs < 0.0 {
@@ -488,6 +530,7 @@ fn pathlock_config_from_value(
Ok(PathLockConfig {
provider,
service_name: pathlock_service_name,
+ sqlite_path,
lock_timeout_secs,
lock_expire_secs,
})
@@ -3418,6 +3461,163 @@ mod tests {
assert_eq!(pathlock.service_name.as_deref(), Some("prod-a"));
}
+ #[test]
+ fn constructor_sqlite_config_path_resolves_defaults_and_creates_parent() {
+ let root = std::env::temp_dir().join(format!(
+ "openviking-sqlite-config-path-{}-{}",
+ std::process::id(),
+ std::time::SystemTime::now()
+ .duration_since(std::time::UNIX_EPOCH)
+ .unwrap()
+ .as_nanos()
+ ));
+ fs::create_dir_all(&root).unwrap();
+ Python::initialize();
+ Python::attach(|py| {
+ for mode in ["omitted", "null", "explicit"] {
+ let workspace = root.join(mode).join("workspace");
+ let database = if mode == "explicit" {
+ root.join(mode).join("custom").join("locks.db")
+ } else {
+ workspace.join("_system/pathlock/pathlock.db")
+ };
+ let mut pathlock = serde_json::json!({"provider": "sqlite"});
+ if mode == "null" {
+ pathlock["sqlite_path"] = serde_json::Value::Null;
+ } else if mode == "explicit" {
+ pathlock["sqlite_path"] = serde_json::json!(database);
+ }
+ let path = root.join(format!("{mode}.json"));
+ fs::write(
+ &path,
+ serde_json::json!({
+ "storage": {
+ "workspace": workspace,
+ "agfs": {"pathlock": pathlock}
+ }
+ })
+ .to_string(),
+ )
+ .unwrap();
+ assert!(!database.parent().unwrap().exists());
+ let config = PyDict::new(py);
+ config.set_item("service_name", "local-a").unwrap();
+ let kwargs = PyDict::new(py);
+ kwargs
+ .set_item("config_path", path.to_str().unwrap())
+ .unwrap();
+ kwargs.set_item("config", config).unwrap();
+ let ty = py.get_type::<RAGFSBindingClient>();
+ let first = ty.call((), Some(&kwargs)).unwrap();
+ let second = ty.call((), Some(&kwargs)).unwrap();
+ assert!(database.is_file());
+ if mode == "explicit" {
+ assert!(!workspace.join("_system/pathlock/pathlock.db").exists());
+ }
+ let first = first.extract::<PyRef<'_, RAGFSBindingClient>>().unwrap();
+ let second = second.extract::<PyRef<'_, RAGFSBindingClient>>().unwrap();
+ let lease = first
+ .rt
+ .block_on(first.pathlock_manager.acquire_tree(
+ "/missing",
+ std::time::Duration::ZERO,
+ None,
+ ))
+ .unwrap();
+ assert!(second
+ .rt
+ .block_on(second.pathlock_manager.acquire_exact(
+ "/missing/child",
+ std::time::Duration::ZERO,
+ None,
+ ))
+ .is_err());
+ first
+ .rt
+ .block_on(first.pathlock_manager.release(&lease))
+ .unwrap();
+ let lease = second
+ .rt
+ .block_on(second.pathlock_manager.acquire_exact(
+ "/missing/child",
+ std::time::Duration::ZERO,
+ None,
+ ))
+ .unwrap();
+ second
+ .rt
+ .block_on(second.pathlock_manager.release(&lease))
+ .unwrap();
+ }
+ });
+ fs::remove_dir_all(root).unwrap();
+ }
+
+ #[test]
+ fn canonical_sqlite_default_requires_workspace_and_preserves_explicit_path() {
+ for pathlock in [
+ serde_json::json!({"provider": "sqlite"}),
+ serde_json::json!({"provider": "sqlite", "sqlite_path": null}),
+ ] {
+ let json = serde_json::json!({
+ "storage": {"workspace": "relative/workspace", "agfs": {"pathlock": pathlock}}
+ });
+ let config = pathlock_config_from_canonical_ov_conf(&json, "local-a").unwrap();
+ let expected = std::path::absolute("relative/workspace")
+ .unwrap()
+ .join("_system/pathlock/pathlock.db");
+ assert_eq!(config.sqlite_path.as_deref(), expected.to_str());
+ assert_eq!(config.service_name.as_deref(), Some("local-a"));
+ }
+ for workspace in [
+ serde_json::Value::Null,
+ serde_json::json!(""),
+ serde_json::json!(42),
+ ] {
+ let json = serde_json::json!({
+ "storage": {"workspace": workspace, "agfs": {"pathlock": {"provider": "sqlite"}}}
+ });
+ let error = pathlock_config_from_canonical_ov_conf(&json, "local-a").unwrap_err();
+ assert!(error.contains("storage.workspace"), "{error}");
+ }
+ let path = std::env::temp_dir().join("explicit-pathlock.db");
+ let json = serde_json::json!({
+ "storage": {"agfs": {"pathlock": {"provider": "sqlite", "sqlite_path": path}}}
+ });
+ assert_eq!(
+ pathlock_config_from_canonical_ov_conf(&json, "local-a")
+ .unwrap()
+ .sqlite_path
+ .as_deref(),
+ path.to_str()
+ );
+ assert_eq!(
+ pathlock_config_from_canonical_ov_conf(&serde_json::json!({}), "local-a")
+ .unwrap()
+ .provider,
+ "filesystem"
+ );
+ }
+
+ #[test]
+ fn sqlite_pathlock_config_parses_shared_path_and_namespace() {
+ let path = std::env::temp_dir().join("openviking-locks.sqlite3");
+ let config = pathlock_config_from_value(
+ &serde_json::json!({"provider": "sqlite", "sqlite_path": path}),
+ "local-a",
+ )
+ .unwrap();
+ assert_eq!(config.sqlite_path.as_deref(), path.to_str());
+ assert_eq!(config.service_name.as_deref(), Some("local-a"));
+ for value in [
+ serde_json::json!({"provider": "sqlite"}),
+ serde_json::json!({"provider": "sqlite", "sqlite_path": "relative.db"}),
+ serde_json::json!({"provider": "sqlite", "sqlite_path": 42}),
+ ] {
+ assert!(pathlock_config_from_value(&value, "local-a").is_err());
+ }
+ }
+
#[test]
fn canonical_cache_config_is_parsed_from_ov_conf() {
let path = std::env::temp_dir().join(format!(
diff --git a/crates/ragfs/Cargo.toml b/crates/ragfs/Cargo.toml
index 32b8f7129..742a80826 100644
--- a/crates/ragfs/Cargo.toml
+++ b/crates/ragfs/Cargo.toml
@@ -18,6 +18,10 @@ path = "src/lib.rs"
name = "ragfs-shell"
path = "src/shell/main.rs"
+[[bench]]
+name = "pathlock_perf"
+harness = false
+
[[test]]
name = "cache_runtime"
path = "tests/cache_runtime.rs"
diff --git a/crates/ragfs/benches/pathlock_perf.md b/crates/ragfs/benches/pathlock_perf.md
new file mode 100644
index 000000000..50711bdea
--- /dev/null
+++ b/crates/ragfs/benches/pathlock_perf.md
@@ -0,0 +1,50 @@
+# PathLock performance baselines
+
+Run from the repository root:
+
+```sh
+cargo bench --locked -p ragfs --bench pathlock_perf -- \
+ --mode all --iterations 20 --worker-iterations 100 --workers 1,4,16 \
+ --output /tmp/pathlock-perf.csv
+```
+
+Use `--mode tree` or `--mode concurrency` to run either benchmark independently.
+These are manual measurements, with no timing thresholds in CI. No server, model,
+Redis service, or additional dependencies are required. All business data, databases,
+and subprocess coordination files live in temporary directories and are cleaned up.
+
+The Tree benchmark compares SQLite and filesystem providers on the same real
+LocalFS datasets: 10–10,000 flat files, plus 200/1,000 subdirectories with one file
+each. Setup and three warmup acquisitions are excluded. Latencies measure
+`acquire_tree` only; locks are released between samples. `directory_reads` counts
+directory listing calls during measured acquire/release cycles, not individual
+metadata system calls. A lightweight atomic counter wraps LocalFS and forwards
+native CAS operations. SQLite keeps its database outside the business subtree.
+
+The concurrency benchmark uses 1/4/16 workers on disjoint existing file paths.
+Each measured operation uses a different path, so a failed release does not turn
+the following samples into logical conflicts on the same retained token.
+It exercises `PathLockManager` with `timeout=0`, with no benchmark-side Busy
+retries. It compares shared-provider threads (SQLite's single connection/mutex),
+independent-provider threads (separate SQLite connections), and separate processes
+sharing the same filesystem and database. Each worker warms up three operations
+before a start barrier. Each runtime uses four Tokio worker threads, including
+each subprocess. Latencies include both acquire and release, including
+scheduling, mutex queues, and database waits. Logical lock contention is deliberately
+excluded so database contention failures remain visible.
+
+CSV rows include successful operations/second, successful-operation P50/P95/P99,
+and failure counts by acquisition/release phase and Timeout/Busy error type.
+All workers' latency samples are pooled; quantiles use nearest
+rank. Throughput uses the controller's wall time, including barrier/reporting
+overhead, especially for subprocesses. Failed operations are counted separately
+and excluded from latency percentiles; always check failures before comparing rates.
+
+The benchmark uses SQLite WAL with `synchronous=FULL` and the production 100 ms
+Busy timeout per attempt, with three total attempts and 1 ms / 4 ms backoff.
+Retries are inside the provider and cover all operations; the benchmark adds none.
+It measures warm filesystem caches, not cold storage or application
+file deletion/copy time. Twenty Tree samples give only a coarse tail estimate.
+Repeat runs on otherwise idle hardware, record OS/CPU/Rust version, and use more
+samples for stable P95/P99 comparisons. Thread and process results are different
+workloads and should not be interpreted as a pure connection-pool speedup.
diff --git a/crates/ragfs/benches/pathlock_perf.rs b/crates/ragfs/benches/pathlock_perf.rs
new file mode 100644
index 000000000..4221d04bd
--- /dev/null
+++ b/crates/ragfs/benches/pathlock_perf.rs
@@ -0,0 +1,589 @@
+//! Manual release-mode benchmarks; see pathlock_perf.md for the measurement contract.
+use std::collections::HashMap;
+use std::fs::{self, File};
+use std::io::Write;
+use std::path::{Path, PathBuf};
+use std::process::{Child, Command};
+use std::sync::atomic::{AtomicU64, Ordering};
+use std::sync::Arc;
+use std::time::{Duration, Instant};
+
+use async_trait::async_trait;
+use ragfs::core::{FileInfo, FileSystem, ListSortBy, Result as FsResult, SortOrder, WriteFlag};
+use ragfs::lock::types::PathLockError;
+use ragfs::lock::{
+ FilesystemPathLockProvider, PathLockConfig, PathLockManager, PathLockProvider,
+ SQLitePathLockProvider,
+};
+use ragfs::plugins::localfs::LocalFileSystem;
+use serde::{Deserialize, Serialize};
+use tempfile::TempDir;
+use tokio::sync::{mpsc, Barrier};
+
+type Result<T> = std::result::Result<T, Box<dyn std::error::Error + Send + Sync>>;
+
+#[derive(Clone)]
+struct Options {
+ mode: String,
+ iterations: usize,
+ worker_iterations: usize,
+ workers: Vec<usize>,
+ args: HashMap<String, String>,
+}
+
+impl Options {
+ fn parse() -> Result<Self> {
+ let mut args = HashMap::new();
+ let mut input = std::env::args().skip(1);
+ while let Some(key) = input.next() {
+ match key.as_str() {
+ "--bench" => {}
+ "--worker" => {
+ args.insert(key, "true".into());
+ }
+ "--help" | "-h" => {
+ println!(
+ "cargo bench --locked -p ragfs --bench pathlock_perf -- \
+ --mode all|tree|concurrency --iterations 20 \
+ --worker-iterations 100 --workers 1,4,16 --output /tmp/pathlock.csv"
+ );
+ std::process::exit(0);
+ }
+ _ => {
+ args.insert(key, input.next().ok_or("missing option value")?);
+ }
+ }
+ }
+ let options = Self {
+ mode: args.get("--mode").cloned().unwrap_or("all".into()),
+ iterations: args
+ .get("--iterations")
+ .map(|s| s.parse())
+ .transpose()?
+ .unwrap_or(20),
+ worker_iterations: args
+ .get("--worker-iterations")
+ .map(|s| s.parse())
+ .transpose()?
+ .unwrap_or(100),
+ workers: args
+ .get("--workers")
+ .map(String::as_str)
+ .unwrap_or("1,4,16")
+ .split(',')
+ .map(str::parse)
+ .collect::<std::result::Result<_, _>>()?,
+ args,
+ };
+ if options.iterations == 0
+ || options.worker_iterations == 0
+ || options.workers.iter().any(|n| *n == 0)
+ || !matches!(options.mode.as_str(), "all" | "tree" | "concurrency")
+ {
+ return Err(
+ "iterations/workers must be positive and mode must be all, tree, or concurrency"
+ .into(),
+ );
+ }
+ Ok(options)
+ }
+
+ fn required(&self, key: &str) -> Result<&str> {
+ self.args
+ .get(key)
+ .map(String::as_str)
+ .ok_or_else(|| format!("missing {key}").into())
+ }
+}
+
+#[derive(Default, Serialize, Deserialize)]
+struct Samples {
+ latency_ns: Vec<u64>,
+ failures: usize,
+ acquire_failures: usize,
+ release_failures: usize,
+ timeouts: usize,
+ busy_errors: usize,
+}
+
+impl Samples {
+ fn merge(&mut self, other: Self) {
+ self.latency_ns.extend(other.latency_ns);
+ self.failures += other.failures;
+ self.acquire_failures += other.acquire_failures;
+ self.release_failures += other.release_failures;
+ self.timeouts += other.timeouts;
+ self.busy_errors += other.busy_errors;
+ }
+
+ fn failed(&mut self, path: &str, phase: &str, error: &PathLockError) {
+ if self.failures == 0 {
+ eprintln!("first {phase} failure at {path}: {error}");
+ }
+ self.failures += 1;
+ if phase == "acquire" {
+ self.acquire_failures += 1;
+ } else {
+ self.release_failures += 1;
+ }
+ self.timeouts += usize::from(matches!(error, PathLockError::Timeout { .. }));
+ self.busy_errors += usize::from(matches!(error, PathLockError::Busy { .. }));
+ }
+}
+
+struct Record {
+ case: String,
+ provider: String,
+ concurrency: usize,
+ files: usize,
+ directories: usize,
+ scope: &'static str,
+ elapsed: Duration,
+ samples: Samples,
+ directory_reads: Option<u64>,
+}
+
+// Count only directory listings. Delegate native CAS operations explicitly so
+// instrumentation cannot change the real filesystem locking protocol.
+struct CountingFS {
+ inner: LocalFileSystem,
+ directory_reads: AtomicU64,
+}
+
+#[async_trait]
+impl FileSystem for CountingFS {
+ async fn create(&self, path: &str) -> FsResult<()> {
+ self.inner.create(path).await
+ }
+ async fn mkdir(&self, path: &str, mode: u32) -> FsResult<()> {
+ self.inner.mkdir(path, mode).await
+ }
+ async fn remove(&self, path: &str) -> FsResult<()> {
+ self.inner.remove(path).await
+ }
+ async fn remove_all(&self, path: &str) -> FsResult<()> {
+ self.inner.remove_all(path).await
+ }
+ async fn read(&self, path: &str, offset: u64, size: u64) -> FsResult<Vec<u8>> {
+ self.inner.read(path, offset, size).await
+ }
+ async fn write(&self, path: &str, data: &[u8], offset: u64, flags: WriteFlag) -> FsResult<u64> {
+ self.inner.write(path, data, offset, flags).await
+ }
+ async fn compare_and_write(&self, path: &str, expected: &[u8], data: &[u8]) -> FsResult<bool> {
+ self.inner.compare_and_write(path, expected, data).await
+ }
+ async fn compare_and_remove(&self, path: &str, expected: &[u8]) -> FsResult<bool> {
+ self.inner.compare_and_remove(path, expected).await
+ }
+ async fn read_dir(
+ &self,
+ path: &str,
+ offset: Option<usize>,
+ limit: Option<usize>,
+ sort_by: Option<ListSortBy>,
+ sort_order: Option<SortOrder>,
+ ) -> FsResult<Vec<FileInfo>> {
+ self.directory_reads.fetch_add(1, Ordering::Relaxed);
+ self.inner
+ .read_dir(path, offset, limit, sort_by, sort_order)
+ .await
+ }
+ async fn read_internal_dir(&self, path: &str) -> FsResult<Vec<FileInfo>> {
+ self.directory_reads.fetch_add(1, Ordering::Relaxed);
+ self.inner.read_internal_dir(path).await
+ }
+ async fn stat(&self, path: &str) -> FsResult<FileInfo> {
+ self.inner.stat(path).await
+ }
+ async fn rename(&self, from: &str, to: &str) -> FsResult<()> {
+ self.inner.rename(from, to).await
+ }
+ async fn chmod(&self, path: &str, mode: u32) -> FsResult<()> {
+ self.inner.chmod(path, mode).await
+ }
+ async fn exists(&self, path: &str) -> bool {
+ self.inner.exists(path).await
+ }
+ async fn ensure_parent_dirs(&self, path: &str, mode: u32) -> FsResult<()> {
+ self.inner.ensure_parent_dirs(path, mode).await
+ }
+}
+
+struct Output {
+ csv: Option<File>,
+}
+
+impl Output {
+ fn new(path: Option<&String>) -> Result<Self> {
+ let mut output = Self {
+ csv: path.map(File::create).transpose()?,
+ };
+ output.line("case,provider,workers,files,directories,latency_scope,successes,failures,elapsed_s,successful_ops_s,p50_ms,p95_ms,p99_ms,directory_reads,acquire_failures,release_failures,timeouts,busy_errors")?;
+ Ok(output)
+ }
+
+ fn line(&mut self, line: &str) -> Result<()> {
+ println!("{line}");
+ if let Some(csv) = &mut self.csv {
+ writeln!(csv, "{line}")?;
+ csv.flush()?;
+ }
+ Ok(())
+ }
+
+ fn record(&mut self, mut record: Record) -> Result<()> {
+ record.samples.latency_ns.sort_unstable();
+ let quantile = |q: f64| -> String {
+ let values = &record.samples.latency_ns;
+ if values.is_empty() {
+ return String::new();
+ }
+ let index = ((q * values.len() as f64).ceil() as usize).saturating_sub(1);
+ format!(
+ "{:.6}",
+ values[index.min(values.len() - 1)] as f64 / 1_000_000.0
+ )
+ };
+ self.line(&format!(
+ "{},{},{},{},{},{},{},{},{:.6},{:.3},{},{},{},{},{},{},{},{}",
+ record.case,
+ record.provider,
+ record.concurrency,
+ record.files,
+ record.directories,
+ record.scope,
+ record.samples.latency_ns.len(),
+ record.samples.failures,
+ record.elapsed.as_secs_f64(),
+ record.samples.latency_ns.len() as f64 / record.elapsed.as_secs_f64(),
+ quantile(0.5),
+ quantile(0.95),
+ quantile(0.99),
+ record
+ .directory_reads
+ .map(|n| n.to_string())
+ .unwrap_or_default(),
+ record.samples.acquire_failures,
+ record.samples.release_failures,
+ record.samples.timeouts,
+ record.samples.busy_errors,
+ ))
+ }
+}
+
+fn make_fs(root: &Path) -> Result<Arc<CountingFS>> {
+ Ok(Arc::new(CountingFS {
+ inner: LocalFileSystem::new(root.to_str().ok_or("non-UTF8 root")?)?,
+ directory_reads: AtomicU64::new(0),
+ }))
+}
+
+fn make_provider(
+ name: &str,
+ fs: Arc<dyn FileSystem>,
+ db: &Path,
+) -> Result<Arc<dyn PathLockProvider>> {
+ match name {
+ "filesystem" => Ok(Arc::new(FilesystemPathLockProvider::new(fs, 30.0))),
+ "sqlite" => Ok(Arc::new(SQLitePathLockProvider::new(
+ db.to_str().ok_or("non-UTF8 database")?,
+ "pathlock-perf",
+ )?)),
+ _ => Err(format!("unknown provider: {name}").into()),
+ }
+}
+
+async fn cycle(manager: &PathLockManager, path: &str, samples: &mut Samples) {
+ let start = Instant::now();
+ match manager.acquire_exact(path, Duration::ZERO, None).await {
+ Ok(lease) => match manager.release(&lease).await {
+ Ok(()) => samples.latency_ns.push(start.elapsed().as_nanos() as u64),
+ Err(error) => samples.failed(path, "release", &error),
+ },
+ Err(error) => {
+ samples.failed(path, "acquire", &error);
+ }
+ }
+}
+
+async fn tree(options: &Options, output: &mut Output) -> Result<()> {
+ // Flat trees expose per-entry metadata cost; nested trees expose per-directory I/O.
+ for (files, dirs) in [
+ (10, 0),
+ (200, 0),
+ (1_000, 0),
+ (5_000, 0),
+ (10_000, 0),
+ (200, 200),
+ (1_000, 1_000),
+ ] {
+ let temp = TempDir::new()?;
+ let root = temp.path().join("data");
+ fs::create_dir_all(root.join("tree"))?;
+ for id in 0..files {
+ let parent = if dirs == 0 {
+ root.join("tree")
+ } else {
+ let parent = root.join(format!("tree/d{id:05}"));
+ fs::create_dir_all(&parent)?;
+ parent
+ };
+ fs::write(parent.join(format!("f{id:05}")), b"x")?;
+ }
+ for name in ["filesystem", "sqlite"] {
+ let tracked = make_fs(&root)?;
+ let provider = make_provider(name, tracked.clone(), &temp.path().join("locks.db"))?;
+ let manager =
+ PathLockManager::new(tracked.clone(), provider, PathLockConfig::default());
+ for _ in 0..3 {
+ let lease = manager.acquire_tree("/tree", Duration::ZERO, None).await?;
+ manager.release(&lease).await?;
+ }
+ let before = tracked.directory_reads.load(Ordering::Relaxed);
+ let mut samples = Samples::default();
+ let wall = Instant::now();
+ for _ in 0..options.iterations {
+ let start = Instant::now();
+ let lease = manager.acquire_tree("/tree", Duration::ZERO, None).await?;
+ samples.latency_ns.push(start.elapsed().as_nanos() as u64);
+ manager.release(&lease).await?;
+ }
+ let elapsed = wall.elapsed();
+ let after = tracked.directory_reads.load(Ordering::Relaxed);
+ output.record(Record {
+ case: if dirs == 0 {
+ "tree_flat"
+ } else {
+ "tree_nested"
+ }
+ .into(),
+ provider: name.into(),
+ concurrency: 1,
+ files,
+ directories: dirs,
+ scope: "acquire",
+ elapsed,
+ samples,
+ directory_reads: Some(after - before),
+ })?;
+ }
+ }
+ Ok(())
+}
+
+fn prepare_work(root: &Path, workers: usize, iterations: usize) -> Result<()> {
+ fs::create_dir_all(root.join("work"))?;
+ for id in 0..workers {
+ for iteration in 0..iterations + 3 {
+ fs::write(root.join(format!("work/{id}-{iteration}")), b"x")?;
+ }
+ }
+ Ok(())
+}
+
+async fn threads(options: &Options, name: &str, workers: usize, shared: bool) -> Result<Record> {
+ let temp = TempDir::new()?;
+ let root = temp.path().join("data");
+ prepare_work(&root, workers, options.worker_iterations)?;
+ let tracked = make_fs(&root)?;
+ let db = temp.path().join("locks.db");
+ let common = make_provider(name, tracked.clone(), &db)?;
+ let barrier = Arc::new(Barrier::new(workers + 1));
+ let (ready_tx, mut ready_rx) = mpsc::channel(workers);
+ let mut tasks = Vec::new();
+ for id in 0..workers {
+ let provider = if shared {
+ common.clone()
+ } else {
+ make_provider(name, tracked.clone(), &db)?
+ };
+ let manager = PathLockManager::new(tracked.clone(), provider, PathLockConfig::default());
+ let barrier = barrier.clone();
+ let ready_tx = ready_tx.clone();
+ let iterations = options.worker_iterations;
+ tasks.push(tokio::spawn(async move {
+ let mut warmup = Samples::default();
+ for iteration in 0..3 {
+ cycle(&manager, &format!("/work/{id}-{iteration}"), &mut warmup).await;
+ }
+ ready_tx.send(()).await.unwrap();
+ barrier.wait().await;
+ let mut samples = Samples::default();
+ for iteration in 3..iterations + 3 {
+ cycle(&manager, &format!("/work/{id}-{iteration}"), &mut samples).await;
+ }
+ samples
+ }));
+ }
+ for _ in 0..workers {
+ ready_rx
+ .recv()
+ .await
+ .ok_or("worker failed before barrier")?;
+ }
+ let before = tracked.directory_reads.load(Ordering::Relaxed);
+ let wall = Instant::now();
+ barrier.wait().await;
+ let mut samples = Samples::default();
+ for task in tasks {
+ samples.merge(task.await?);
+ }
+ let elapsed = wall.elapsed();
+ let after = tracked.directory_reads.load(Ordering::Relaxed);
+ Ok(Record {
+ case: if shared {
+ "threads_shared_provider"
+ } else {
+ "threads_independent_providers"
+ }
+ .into(),
+ provider: name.into(),
+ concurrency: workers,
+ files: workers * (options.worker_iterations + 3),
+ directories: 0,
+ scope: "acquire_release",
+ elapsed,
+ samples,
+ directory_reads: Some(after - before),
+ })
+}
+
+fn wait_for(path: &Path) -> Result<()> {
+ let start = Instant::now();
+ while !path.exists() {
+ if start.elapsed() > Duration::from_secs(60) {
+ return Err(format!("timed out waiting for {path:?}").into());
+ }
+ std::thread::sleep(Duration::from_millis(1));
+ }
+ Ok(())
+}
+
+struct Worker(Child);
+impl Drop for Worker {
+ fn drop(&mut self) {
+ let _ = self.0.kill();
+ let _ = self.0.wait();
+ }
+}
+
+async fn process_worker(options: &Options) -> Result<()> {
+ let root = PathBuf::from(options.required("--root")?);
+ let db = PathBuf::from(options.required("--db")?);
+ let sync = PathBuf::from(options.required("--sync")?);
+ let id = options.required("--id")?;
+ let tracked = make_fs(&root)?;
+ let provider = make_provider(options.required("--provider")?, tracked.clone(), &db)?;
+ let manager = PathLockManager::new(tracked, provider, PathLockConfig::default());
+ let mut warmup = Samples::default();
+ for iteration in 0..3 {
+ cycle(&manager, &format!("/work/{id}-{iteration}"), &mut warmup).await;
+ }
+ fs::write(sync.join(format!("{id}.ready")), "")?;
+ wait_for(&sync.join("go"))?;
+ let mut samples = Samples::default();
+ for iteration in 3..options.worker_iterations + 3 {
+ cycle(&manager, &format!("/work/{id}-{iteration}"), &mut samples).await;
+ }
+ let temp_report = sync.join(format!("{id}.json.tmp"));
+ fs::write(&temp_report, serde_json::to_vec(&samples)?)?;
+ fs::rename(temp_report, sync.join(format!("{id}.json")))?;
+ Ok(())
+}
+
+fn processes(options: &Options, name: &str, workers: usize) -> Result<Record> {
+ let temp = TempDir::new()?;
+ let root = temp.path().join("data");
+ let db = temp.path().join("locks.db");
+ let sync = temp.path().join("sync");
+ prepare_work(&root, workers, options.worker_iterations)?;
+ fs::create_dir(&sync)?;
+ // Exclude concurrent schema initialization from measurements.
+ drop(make_provider(name, make_fs(&root)?, &db)?);
+ let mut children = Vec::new();
+ for id in 0..workers {
+ children.push(Worker(
+ Command::new(std::env::current_exe()?)
+ .arg("--worker")
+ .arg("--provider")
+ .arg(name)
+ .arg("--root")
+ .arg(&root)
+ .arg("--db")
+ .arg(&db)
+ .arg("--sync")
+ .arg(&sync)
+ .arg("--id")
+ .arg(id.to_string())
+ .arg("--worker-iterations")
+ .arg(options.worker_iterations.to_string())
+ .spawn()?,
+ ));
+ }
+ let deadline = Instant::now();
+ loop {
+ if (0..workers).all(|id| sync.join(format!("{id}.ready")).exists()) {
+ break;
+ }
+ for worker in &mut children {
+ if let Some(status) = worker.0.try_wait()? {
+ return Err(format!("worker exited before start: {status}").into());
+ }
+ }
+ if deadline.elapsed() > Duration::from_secs(60) {
+ return Err("worker initialization timed out".into());
+ }
+ std::thread::sleep(Duration::from_millis(1));
+ }
+ let wall = Instant::now();
+ fs::write(sync.join("go"), "")?;
+ let mut samples = Samples::default();
+ for id in 0..workers {
+ let report = sync.join(format!("{id}.json"));
+ wait_for(&report)?;
+ samples.merge(serde_json::from_slice(&fs::read(report)?)?);
+ }
+ let elapsed = wall.elapsed();
+ for worker in &mut children {
+ if !worker.0.wait()?.success() {
+ return Err("worker failed".into());
+ }
+ }
+ Ok(Record {
+ case: "processes_independent_providers".into(),
+ provider: name.into(),
+ concurrency: workers,
+ files: workers * (options.worker_iterations + 3),
+ directories: 0,
+ scope: "acquire_release",
+ elapsed,
+ samples,
+ directory_reads: None,
+ })
+}
+
+#[tokio::main(flavor = "multi_thread", worker_threads = 4)]
+async fn main() -> Result<()> {
+ let options = Options::parse()?;
+ if options.args.contains_key("--worker") {
+ return process_worker(&options).await;
+ }
+ eprintln!("pathlock_perf os={} arch={} available_parallelism={} runtime_threads=4 tree_samples={} per_worker_samples={} sqlite=WAL/FULL busy_ms=100 busy_attempts=3 backoff_ms=1,4",
+ std::env::consts::OS, std::env::consts::ARCH, std::thread::available_parallelism()?,
+ options.iterations, options.worker_iterations);
+ let mut output = Output::new(options.args.get("--output"))?;
+ if matches!(options.mode.as_str(), "all" | "tree") {
+ tree(&options, &mut output).await?;
+ }
+ if matches!(options.mode.as_str(), "all" | "concurrency") {
+ for &workers in &options.workers {
+ for name in ["filesystem", "sqlite"] {
+ output.record(threads(&options, name, workers, true).await?)?;
+ output.record(threads(&options, name, workers, false).await?)?;
+ output.record(processes(&options, name, workers)?)?;
+ }
+ }
+ }
+ Ok(())
+}
diff --git a/crates/ragfs/src/core/builder.rs b/crates/ragfs/src/core/builder.rs
index 450332081..0cb39fec6 100644
--- a/crates/ragfs/src/core/builder.rs
+++ b/crates/ragfs/src/core/builder.rs
@@ -26,7 +26,7 @@ use crate::cache_runtime::{
use crate::lock::RedisPathLockProvider;
use crate::lock::{
FilesystemPathLockProvider, MemoryPathLockProvider, PathLockConfig, PathLockManager,
- PathLockProvider, PathLockWrappedFS,
+ PathLockProvider, PathLockWrappedFS, SQLitePathLockProvider,
};
#[cfg(feature = "s3")]
@@ -233,6 +233,39 @@ async fn build_stack_with_mountable_and_runtime(
config.pathlock.lock_expire_secs,
)),
"memory" => Arc::new(MemoryPathLockProvider::new()),
+ "sqlite" => {
+ let path = config.pathlock.sqlite_path.as_deref().ok_or_else(|| {
+ Error::config("pathlock.sqlite_path is required for SQLite PathLock")
+ })?;
+ let namespace = config.pathlock.service_name.as_deref().ok_or_else(|| {
+ Error::config("pathlock.service_name is required for SQLite PathLock")
+ })?;
+ let path = path.to_string();
+ let namespace = namespace.to_string();
+ let provider = tokio::task::spawn_blocking(move || {
+ let database = std::path::Path::new(&path);
+ if !database.is_absolute() || namespace.trim().is_empty() {
+ return Err(crate::lock::types::PathLockError::InvalidRequest(
+ "SQLite PathLock requires an absolute sqlite_path and nonempty service_name"
+ .to_string(),
+ ));
+ }
+ if let Some(parent) = database.parent() {
+ std::fs::create_dir_all(parent).map_err(|error| {
+ crate::lock::types::PathLockError::Io(format!(
+ "failed to create SQLite PathLock parent directory: {error}"
+ ))
+ })?;
+ }
+ SQLitePathLockProvider::new(&path, &namespace)
+ })
+ .await
+ .map_err(|error| Error::config(format!("SQLite PathLock worker failed: {error}")))?
+ .map_err(|error| {
+ Error::config(format!("SQLite PathLock initialization failed: {error}"))
+ })?;
+ Arc::new(provider)
+ }
#[cfg(feature = "cache")]
"cache" => {
let runtime = runtime.clone().ok_or_else(|| {
@@ -353,6 +386,7 @@ mod tests {
pathlock: PathLockConfig {
provider: "filesystem".to_string(),
service_name: None,
+ sqlite_path: None,
lock_timeout_secs: 0.0,
lock_expire_secs: 30.0,
},
@@ -534,6 +568,45 @@ mod tests {
assert!(stack.cache_runtime.is_none());
}
+ #[tokio::test]
+ async fn default_stack_builds_sqlite_pathlock_without_cache() {
+ let dir = tempfile::tempdir().unwrap();
+ let config = RagfsConfig {
+ pathlock: PathLockConfig {
+ provider: "sqlite".into(),
+ service_name: Some("builder-test".into()),
+ sqlite_path: Some(dir.path().join("locks.db").to_str().unwrap().into()),
+ ..PathLockConfig::default()
+ },
+ ..RagfsConfig::default()
+ };
+ let stack = build_default_stack(config).await.unwrap();
+ let lease = stack
+ .pathlock_manager
+ .acquire_tree("/missing", std::time::Duration::ZERO, None)
+ .await
+ .unwrap();
+ assert_eq!(lease.lease.lock_paths, vec!["/missing"]);
+ stack.pathlock_manager.release(&lease).await.unwrap();
+ }
+
+ #[tokio::test]
+ async fn default_stack_rejects_sqlite_pathlock_without_shared_database() {
+ let config = RagfsConfig {
+ pathlock: PathLockConfig {
+ provider: "sqlite".into(),
+ service_name: Some("builder-test".into()),
+ ..PathLockConfig::default()
+ },
+ ..RagfsConfig::default()
+ };
+ let error = match build_default_stack(config).await {
+ Ok(_) => panic!("SQLite PathLock unexpectedly built without database"),
+ Err(error) => error,
+ };
+ assert!(error.to_string().contains("sqlite_path"));
+ }
+
#[tokio::test]
async fn default_stack_rejects_unknown_pathlock_provider() {
let config = RagfsConfig {
diff --git a/crates/ragfs/src/lock/cache_provder.rs b/crates/ragfs/src/lock/cache_provder.rs
index 4cac8233e..f03d36786 100644
--- a/crates/ragfs/src/lock/cache_provder.rs
+++ b/crates/ragfs/src/lock/cache_provder.rs
@@ -11,10 +11,12 @@ use crate::cache_runtime::{
};
use super::codec::LockTokenCodec;
-use super::provider::{AcquisitionChange, AtomicAcquisition, PathLockHandleMode, PathLockProvider};
+use super::provider::{
+ AcquisitionChange, AtomicAcquisition, AtomicAcquisitionResult, PathLockHandleMode, PathLockProvider,
+};
use super::types::{LockToken, PathLockError, PathLockKind, PathLockRequest, PathLockResult};
-const ACQUIRE_BATCH_ID: &str = "pathlock.acquire_batch.v1";
+const ACQUIRE_BATCH_ID: &str = "pathlock.acquire_batch.v2";
const ROLLBACK_BATCH_ID: &str = "pathlock.rollback_batch.v1";
const COMPARE_WRITE_ID: &str = "pathlock.compare_write.v1";
const COMPARE_REMOVE_ID: &str = "pathlock.compare_remove.v1";
@@ -258,7 +260,7 @@ if redis.call("HLEN", key) > 0 then
redis.call("PEXPIRE", key, ttl_ms)
end
-local result = { "ok" }
+local result = { "ok", tostring(#stale) }
for _, change in ipairs(changes) do
table.insert(result, change.path)
table.insert(result, change.change)
@@ -789,6 +791,19 @@ impl PathLockProvider for RedisPathLockProvider {
now_ns: u128,
stale_before_ns: u128,
) -> PathLockResult<Option<Vec<AtomicAcquisition>>> {
+ Ok(self
+ .try_acquire_batch_atomic_with_stats(requests, owner_id, now_ns, stale_before_ns)
+ .await?
+ .map(|result| result.acquisitions))
+ }
+
+ async fn try_acquire_batch_atomic_with_stats(
+ &self,
+ requests: &[PathLockRequest],
+ owner_id: &str,
+ now_ns: u128,
+ stale_before_ns: u128,
+ ) -> PathLockResult<Option<AtomicAcquisitionResult>> {
if requests.is_empty() {
return Err(PathLockError::InvalidRequest(
"lock request batch must not be empty".to_string(),
@@ -811,15 +826,18 @@ impl PathLockProvider for RedisPathLockProvider {
if status != "ok" {
return Err(Self::decode_error_result("acquire_batch", &values)?);
}
- if (values.len() - 1) % 4 != 0 {
+ if values.len() < 2 || (values.len() - 2) % 4 != 0 {
return Err(PathLockError::Internal(format!(
"Redis PathLock acquire_batch returned {} trailing values",
- values.len() - 1
+ values.len().saturating_sub(2)
)));
}
- let mut acquisitions = Vec::with_capacity((values.len() - 1) / 4);
- for values in values[1..].chunks_exact(4) {
+ let stale_tokens_removed = Self::result_string(&values[1], "acquire_batch")?
+ .parse::<usize>()
+ .map_err(|_| PathLockError::Internal("invalid Redis stale recovery count".into()))?;
+ let mut acquisitions = Vec::with_capacity((values.len() - 2) / 4);
+ for values in values[2..].chunks_exact(4) {
let handle = Self::result_string(&values[0], "acquire_batch")?.to_string();
let change = Self::result_string(&values[1], "acquire_batch")?;
let previous = Self::result_string(&values[2], "acquire_batch")?;
@@ -841,7 +859,10 @@ impl PathLockProvider for RedisPathLockProvider {
};
acquisitions.push(AtomicAcquisition { handle, change });
}
- Ok(Some(acquisitions))
+ Ok(Some(AtomicAcquisitionResult {
+ acquisitions,
+ stale_tokens_removed,
+ }))
}
/// Atomically roll back mutations reported by one completed batch.
@@ -1315,6 +1336,7 @@ return redis.call("HGET", KEYS[1], ARGV[2])
let config = PathLockConfig {
provider: "cache".to_string(),
service_name: Some(service_name.clone()),
+ sqlite_path: None,
lock_timeout_secs: 0.0,
lock_expire_secs: 3.0,
};
@@ -1962,6 +1984,31 @@ return redis.call("HGET", KEYS[1], ARGV[2])
}
}
+ /// Verify storage-side stale recovery reaches manager metrics.
+ #[tokio::test]
+ async fn stale_recovery_count_reaches_manager_observation() {
+ let Some((runtime, provider)) = test_provider("stale-metrics").await else {
+ return;
+ };
+ let path = "/local/account-a/old";
+ provider
+ .try_create_token(path, &token("dead", 1, PathLockKind::Exact))
+ .await
+ .unwrap();
+ let manager = PathLockManager::new(
+ Arc::new(MemFileSystem::new()),
+ Arc::new(provider),
+ PathLockConfig::default(),
+ );
+ let lease = manager
+ .acquire_tree(path, Duration::ZERO, None)
+ .await
+ .unwrap();
+ assert_eq!(manager.observe().await.stale_locks_removed, 1);
+ manager.release(&lease).await.unwrap();
+ runtime.close().await.unwrap();
+ }
+
/// Measure HASH-only atomic batch latency for representative lock counts.
#[tokio::test]
#[ignore = "manual Redis performance baseline"]
diff --git a/crates/ragfs/src/lock/cache_refresh_tests.rs b/crates/ragfs/src/lock/cache_refresh_tests.rs
index 858fbb199..7548b6286 100644
--- a/crates/ragfs/src/lock/cache_refresh_tests.rs
+++ b/crates/ragfs/src/lock/cache_refresh_tests.rs
@@ -187,7 +187,10 @@ async fn manager_uses_batch_for_manual_and_background_refresh() {
ACQUIRE_BATCH_ID => {
let owner = std::str::from_utf8(&request.args[0]).unwrap();
let time = std::str::from_utf8(&request.args[1]).unwrap();
- let mut results = vec![ScriptValue::Bytes(b"ok".to_vec())];
+ let mut results = vec![
+ ScriptValue::Bytes(b"ok".to_vec()),
+ ScriptValue::Bytes(b"0".to_vec()),
+ ];
for pair in request.args[4..].chunks_exact(2) {
let kind = std::str::from_utf8(&pair[1]).unwrap();
results.extend([
diff --git a/crates/ragfs/src/lock/manager.rs b/crates/ragfs/src/lock/manager.rs
index 2cbe038e2..22b7ed044 100644
--- a/crates/ragfs/src/lock/manager.rs
+++ b/crates/ragfs/src/lock/manager.rs
@@ -28,10 +28,12 @@ use super::types::{
/// Configuration for the PathLockManager.
#[derive(Debug, Clone)]
pub struct PathLockConfig {
- /// Built-in provider name: `filesystem`, `memory`, or `cache`.
+ /// Built-in provider name: `filesystem`, `memory`, `sqlite`, or `cache`.
pub provider: String,
- /// OpenViking instance name used by the cache-backed provider.
+ /// OpenViking instance name used by the SQLite/cache-backed provider.
pub service_name: Option<String>,
+ /// Absolute local database file shared by SQLite lock participants.
+ pub sqlite_path: Option<String>,
/// Default wait timeout for auto-acquired locks.
pub lock_timeout_secs: f64,
/// Seconds after which a lock token is considered stale.
@@ -43,6 +45,7 @@ impl Default for PathLockConfig {
Self {
provider: "filesystem".to_string(),
service_name: None,
+ sqlite_path: None,
lock_timeout_secs: 0.0,
lock_expire_secs: 30.0,
}
@@ -524,10 +527,10 @@ impl PathLockManager {
let pending_handoff = entry.pending_handoff;
let mut any_ok = false;
let mut released_handoff_paths = Vec::new();
- let results = refresh_provider
+ let refresh_results = refresh_provider
.refresh_tokens(&lock_paths, &owner.owner_id, now_ns)
.await;
- for (lp, result) in lock_paths.iter().zip(results) {
+ for (lp, result) in lock_paths.iter().zip(refresh_results) {
match result {
Ok(true) => {
any_ok = true;
@@ -1011,7 +1014,7 @@ impl PathLockManager {
let now_ns = Self::now_ns();
match self
.provider
- .try_acquire_batch_atomic(
+ .try_acquire_batch_atomic_with_stats(
requests,
owner_id,
now_ns,
@@ -1019,7 +1022,12 @@ impl PathLockManager {
)
.await
{
- Ok(Some(acquisitions)) => return Ok(acquisitions),
+ Ok(Some(result)) => {
+ if result.stale_tokens_removed != 0 {
+ self.metrics.write().await.stale_tokens_removed += result.stale_tokens_removed;
+ }
+ return Ok(result.acquisitions);
+ }
Ok(None) => {}
Err(error) => return Err(error),
}
diff --git a/crates/ragfs/src/lock/mod.rs b/crates/ragfs/src/lock/mod.rs
index 67d1a60e2..adb7abe1e 100644
--- a/crates/ragfs/src/lock/mod.rs
+++ b/crates/ragfs/src/lock/mod.rs
@@ -1,7 +1,7 @@
//! PathLock subsystem — native file-system-level locking protocol.
//!
//! This module provides exact-path and tree-path locks backed by lock files,
-//! process memory, or Redis.
+//! process memory, SQLite, or Redis.
//!
//! # Architecture
//!
@@ -19,6 +19,7 @@ pub mod manager;
pub mod metrics;
pub mod provider;
pub mod resolver;
+pub mod sqlite_provider;
pub mod types;
pub mod wrapper;
@@ -28,10 +29,11 @@ pub use cache_provder::RedisPathLockProvider;
pub use manager::{AutoPathLockAction, PathLockConfig, PathLockManager};
pub use metrics::LockMetrics;
pub use provider::{
- AcquisitionChange, AtomicAcquisition, FilesystemPathLockProvider, MemoryPathLockProvider,
- PathLockHandleMode, PathLockProvider,
+ AcquisitionChange, AtomicAcquisition, AtomicAcquisitionResult, FilesystemPathLockProvider,
+ MemoryPathLockProvider, PathLockHandleMode, PathLockProvider,
};
pub use resolver::LockPathResolver;
+pub use sqlite_provider::SQLitePathLockProvider;
pub use types::{
BorrowedPathLockLease, LockToken, OwnedPathLockLease, PathLockConflict, PathLockHandoffRef,
PathLockKind, PathLockLease, PathLockObserveSnapshot, PathLockRequest, PathLockResult,
diff --git a/crates/ragfs/src/lock/provider.rs b/crates/ragfs/src/lock/provider.rs
index 41a130871..52121d971 100644
--- a/crates/ragfs/src/lock/provider.rs
+++ b/crates/ragfs/src/lock/provider.rs
@@ -53,6 +53,15 @@ pub struct AtomicAcquisition {
pub change: AcquisitionChange,
}
+/// Committed atomic acquisition mutations and storage-side recovery statistics.
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct AtomicAcquisitionResult {
+ /// Mutations used to publish or roll back the local lease.
+ pub acquisitions: Vec<AtomicAcquisition>,
+ /// Stale tokens actually removed or replaced by this committed transaction.
+ pub stale_tokens_removed: usize,
+}
+
/// Storage abstraction for lock tokens. Only `PathLockManager` should call these methods.
#[async_trait]
pub trait PathLockProvider: Send + Sync {
@@ -75,6 +84,24 @@ pub trait PathLockProvider: Send + Sync {
Ok(None)
}
+ /// Acquire with recovery statistics. Existing providers keep their atomic hook
+ /// and report zero until they implement storage-side recovery accounting.
+ async fn try_acquire_batch_atomic_with_stats(
+ &self,
+ requests: &[PathLockRequest],
+ owner_id: &str,
+ now_ns: u128,
+ stale_before_ns: u128,
+ ) -> PathLockResult<Option<AtomicAcquisitionResult>> {
+ Ok(self
+ .try_acquire_batch_atomic(requests, owner_id, now_ns, stale_before_ns)
+ .await?
+ .map(|acquisitions| AtomicAcquisitionResult {
+ acquisitions,
+ stale_tokens_removed: 0,
+ }))
+ }
+
/// Roll back one completed atomic acquisition when supported.
async fn rollback_acquisitions_atomic(
&self,
diff --git a/crates/ragfs/src/lock/sqlite_provider.rs b/crates/ragfs/src/lock/sqlite_provider.rs
new file mode 100644
index 000000000..0dfa9af81
--- /dev/null
+++ b/crates/ragfs/src/lock/sqlite_provider.rs
@@ -0,0 +1,644 @@
+//! Same-machine, multi-process locks stored in one authoritative SQLite database.
+
+use std::path::Path;
+use std::sync::{Arc, Mutex};
+use std::time::Duration;
+
+use async_trait::async_trait;
+use rusqlite::{params, Connection, OptionalExtension, TransactionBehavior};
+
+use super::provider::{
+ AcquisitionChange, AtomicAcquisition, AtomicAcquisitionResult, PathLockHandleMode,
+ PathLockProvider,
+};
+use super::types::{LockToken, PathLockError, PathLockKind, PathLockRequest, PathLockResult};
+
+/// Transactional local lock storage. All participants must share the database and namespace.
+pub struct SQLitePathLockProvider {
+ // A single connection also serializes reads. A future read pool can use WAL
+ // snapshots independently while retaining serialized write transactions.
+ conn: Arc<Mutex<Connection>>,
+ namespace: String,
+}
+
+// Absorb transient SQLite writer contention even when the manager's logical
+// lock wait timeout is zero. This wait runs only on a blocking worker thread.
+const SQLITE_BUSY_TIMEOUT: Duration = Duration::from_millis(100);
+// Three total attempts, with 1 ms / 4 ms backoff after Busy. Each attempt keeps
+// SQLite's 100 ms busy timeout; the backoff is additional to database waits.
+const SQLITE_BUSY_ATTEMPTS: usize = 3;
+
+fn db_error(error: rusqlite::Error) -> PathLockError {
+ match &error {
+ rusqlite::Error::SqliteFailure(code, _)
+ if matches!(
+ code.code,
+ rusqlite::ErrorCode::DatabaseBusy | rusqlite::ErrorCode::DatabaseLocked
+ ) =>
+ {
+ PathLockError::Busy {
+ lock_path: "sqlite".to_string(),
+ operation: "transaction".to_string(),
+ }
+ }
+ _ => PathLockError::Io(format!("SQLite PathLock: {error}")),
+ }
+}
+
+// Fixed-width decimal TEXT preserves the entire u128 range and lexical ordering.
+fn timestamp(time_ns: u128) -> String {
+ format!("{time_ns:039}")
+}
+
+fn validate_path(path: &str) -> PathLockResult<()> {
+ if !path.starts_with('/')
+ || (path != "/" && path.ends_with('/'))
+ || path.contains("//")
+ || path.contains('\0')
+ || path.split('/').any(|part| matches!(part, "." | ".."))
+ {
+ return Err(PathLockError::InvalidRequest(format!(
+ "SQLite PathLock requires a normalized absolute logical path: {path}"
+ )));
+ }
+ Ok(())
+}
+
+fn validate_owner(owner: &str) -> PathLockResult<()> {
+ if owner.is_empty() || owner.contains(':') {
+ return Err(PathLockError::InvalidRequest(
+ "lock owner must be nonempty and contain no ':'".to_string(),
+ ));
+ }
+ Ok(())
+}
+
+fn ancestors(path: &str) -> Vec<&str> {
+ if path == "/" {
+ return Vec::new();
+ }
+ let mut result = vec!["/"];
+ for (index, _) in path.match_indices('/').skip(1) {
+ result.push(&path[..index]);
+ }
+ result
+}
+
+fn descendant_bounds(path: &str) -> (String, String) {
+ if path == "/" {
+ ("/".to_string(), "0".to_string())
+ } else {
+ // '/' is immediately followed by '0' in SQLite's BINARY collation.
+ (format!("{path}/"), format!("{path}0"))
+ }
+}
+
+fn decode_row(row: &rusqlite::Row<'_>) -> rusqlite::Result<LockToken> {
+ let time: String = row.get(1)?;
+ let kind: String = row.get(2)?;
+ let invalid = || rusqlite::Error::InvalidQuery;
+ Ok(LockToken {
+ owner_id: row.get(0)?,
+ time_ns: time.parse().map_err(|_| invalid())?,
+ lock_type: match kind.as_str() {
+ "E" => PathLockKind::Exact,
+ "T" => PathLockKind::Tree,
+ _ => return Err(invalid()),
+ },
+ })
+}
+
+fn read(conn: &Connection, namespace: &str, path: &str) -> PathLockResult<Option<LockToken>> {
+ conn.query_row(
+ "SELECT owner, time_ns, kind FROM pathlock_tokens WHERE namespace=?1 AND path=?2",
+ params![namespace, path],
+ decode_row,
+ )
+ .optional()
+ .map_err(db_error)
+}
+
+fn write(conn: &Connection, namespace: &str, path: &str, token: &LockToken) -> PathLockResult<()> {
+ conn.execute(
+ "INSERT INTO pathlock_tokens(namespace, path, owner, time_ns, kind)
+ VALUES (?1,?2,?3,?4,?5)
+ ON CONFLICT(namespace,path) DO UPDATE SET
+ owner=excluded.owner, time_ns=excluded.time_ns, kind=excluded.kind",
+ params![
+ namespace,
+ path,
+ token.owner_id,
+ timestamp(token.time_ns),
+ token.lock_type.to_code().to_string()
+ ],
+ )
+ .map_err(db_error)?;
+ Ok(())
+}
+
+fn conflict(path: &str, token: &LockToken) -> PathLockError {
+ PathLockError::Conflict {
+ lock_path: path.to_string(),
+ owner: token.owner_id.clone(),
+ kind: token.lock_type,
+ }
+}
+
+impl SQLitePathLockProvider {
+ /// Open a persistent local database. Its parent directory must already exist.
+ ///
+ /// Use the same absolute file path and namespace in every cooperating process.
+ /// SQLite file locking is intended for local disks, not network filesystems.
+ /// Runtime SQLite Busy waits use 100 ms per attempt, with at most three
+ /// attempts and 1 ms / 4 ms backoff, independently of the manager's logical
+ /// lock wait timeout. All waits run on blocking worker threads.
+ pub fn new(db_path: &str, namespace: &str) -> PathLockResult<Self> {
+ if !Path::new(db_path).is_absolute() || namespace.trim().is_empty() {
+ return Err(PathLockError::InvalidRequest(
+ "SQLite PathLock requires an absolute sqlite_path and nonempty service_name"
+ .to_string(),
+ ));
+ }
+ let conn = Connection::open(db_path).map_err(db_error)?;
+ // Allow concurrent process initialization.
+ conn.busy_timeout(Duration::from_secs(5))
+ .map_err(db_error)?;
+ // FULL favors durability of committed lock records over NORMAL's lower
+ // synchronization cost; losing a held token could allow conflicting writes.
+ conn.execute_batch(
+ "PRAGMA journal_mode=WAL;
+ PRAGMA synchronous=FULL;
+ CREATE TABLE IF NOT EXISTS pathlock_tokens (
+ namespace TEXT NOT NULL,
+ path TEXT COLLATE BINARY NOT NULL,
+ owner TEXT NOT NULL,
+ time_ns TEXT COLLATE BINARY NOT NULL CHECK(length(time_ns)=39),
+ kind TEXT NOT NULL CHECK(kind IN ('E','T')),
+ PRIMARY KEY(namespace,path)
+ ) WITHOUT ROWID;
+ CREATE INDEX IF NOT EXISTS pathlock_expiry ON pathlock_tokens(namespace,time_ns);",
+ )
+ .map_err(db_error)?;
+ conn.busy_timeout(SQLITE_BUSY_TIMEOUT).map_err(db_error)?;
+ Ok(Self {
+ conn: Arc::new(Mutex::new(conn)),
+ namespace: namespace.to_string(),
+ })
+ }
+
+ async fn run<T, F>(&self, mut operation: F) -> PathLockResult<T>
+ where
+ T: Send + 'static,
+ F: FnMut(&mut Connection, &str) -> PathLockResult<T> + Send + 'static,
+ {
+ let conn = self.conn.clone();
+ let namespace = self.namespace.clone();
+ tokio::task::spawn_blocking(move || {
+ let mut conn = conn
+ .lock()
+ .map_err(|_| PathLockError::Internal("SQLite connection mutex poisoned".into()))?;
+ for attempt in 0..SQLITE_BUSY_ATTEMPTS {
+ match operation(&mut conn, &namespace) {
+ Err(PathLockError::Busy { .. }) if attempt + 1 < SQLITE_BUSY_ATTEMPTS => {
+ // Transaction closures drop (and roll back) before returning.
+ // If rollback failed, clean up before replaying any mutations.
+ if !conn.is_autocommit() {
+ conn.execute_batch("ROLLBACK").map_err(db_error)?;
+ }
+ std::thread::sleep(Duration::from_millis(1 << (2 * attempt)));
+ }
+ result => return result,
+ }
+ }
+ unreachable!("the final Busy attempt returns its error")
+ })
+ .await
+ .map_err(|error| PathLockError::Internal(format!("SQLite worker failed: {error}")))?
+ }
+}
+
+#[async_trait]
+impl PathLockProvider for SQLitePathLockProvider {
+ fn name(&self) -> &'static str {
+ "sqlite"
+ }
+
+ fn handle_mode(&self) -> PathLockHandleMode {
+ PathLockHandleMode::LogicalPath
+ }
+
+ async fn try_acquire_batch_atomic(
+ &self,
+ requests: &[PathLockRequest],
+ owner_id: &str,
+ now_ns: u128,
+ stale_before_ns: u128,
+ ) -> PathLockResult<Option<Vec<AtomicAcquisition>>> {
+ Ok(self
+ .try_acquire_batch_atomic_with_stats(requests, owner_id, now_ns, stale_before_ns)
+ .await?
+ .map(|result| result.acquisitions))
+ }
+
+ async fn try_acquire_batch_atomic_with_stats(
+ &self,
+ requests: &[PathLockRequest],
+ owner_id: &str,
+ now_ns: u128,
+ stale_before_ns: u128,
+ ) -> PathLockResult<Option<AtomicAcquisitionResult>> {
+ validate_owner(owner_id)?;
+ if requests.is_empty() {
+ return Err(PathLockError::InvalidRequest("empty lock batch".into()));
+ }
+ for request in requests {
+ validate_path(&request.path)?;
+ }
+ let requests = requests.to_vec();
+ let owner = owner_id.to_string();
+ self.run(move |conn, namespace| {
+ let tx = conn
+ .transaction_with_behavior(TransactionBehavior::Immediate)
+ .map_err(db_error)?;
+ let stale_before = timestamp(stale_before_ns);
+ // Opportunistic global cleanup is bounded. Conflicting stale records
+ // must also be removed completely below so their owners cannot revive
+ // them after a successful takeover.
+ let mut stale_tokens_removed = tx
+ .execute(
+ "DELETE FROM pathlock_tokens WHERE (namespace,path) IN (
+ SELECT namespace,path FROM pathlock_tokens
+ WHERE namespace=?1 AND time_ns<?2 AND owner<>?3 LIMIT 256)",
+ params![namespace, stale_before, owner],
+ )
+ .map_err(db_error)?;
+ let mut changes = Vec::with_capacity(requests.len());
+ for request in &requests {
+ stale_tokens_removed += tx
+ .execute(
+ "DELETE FROM pathlock_tokens
+ WHERE namespace=?1 AND path=?2 AND owner<>?3 AND time_ns<?4",
+ params![namespace, request.path, owner, stale_before],
+ )
+ .map_err(db_error)?;
+ let existing = read(&tx, namespace, &request.path)?;
+ if let Some(token) = &existing {
+ if token.owner_id != owner && token.time_ns >= stale_before_ns {
+ return Err(conflict(&request.path, token));
+ }
+ }
+ for ancestor in ancestors(&request.path) {
+ stale_tokens_removed += tx
+ .execute(
+ "DELETE FROM pathlock_tokens
+ WHERE namespace=?1 AND path=?2 AND owner<>?3
+ AND time_ns<?4 AND kind='T'",
+ params![namespace, ancestor, owner, stale_before],
+ )
+ .map_err(db_error)?;
+ if let Some(token) = read(&tx, namespace, ancestor)? {
+ if token.lock_type == PathLockKind::Tree
+ && token.owner_id != owner
+ && token.time_ns >= stale_before_ns
+ {
+ return Err(conflict(ancestor, &token));
+ }
+ }
+ }
+ if request.kind == PathLockKind::Tree {
+ let (lower, upper) = descendant_bounds(&request.path);
+ stale_tokens_removed += tx
+ .execute(
+ "DELETE FROM pathlock_tokens
+ WHERE namespace=?1 AND path>=?2 AND path<?3 AND path<>?4
+ AND owner<>?5 AND time_ns<?6",
+ params![namespace, lower, upper, request.path, owner, stale_before],
+ )
+ .map_err(db_error)?;
+ let found = tx
+ .query_row(
+ "SELECT path, owner, time_ns, kind FROM pathlock_tokens
+ WHERE namespace=?1 AND path>=?2 AND path<?3 AND path<>?4
+ AND owner<>?5 AND time_ns>=?6 LIMIT 1",
+ params![namespace, lower, upper, request.path, owner, stale_before],
+ |row| {
+ let path: String = row.get(0)?;
+ Ok((
+ path,
+ LockToken {
+ owner_id: row.get(1)?,
+ time_ns: row
+ .get::<_, String>(2)?
+ .parse()
+ .map_err(|_| rusqlite::Error::InvalidQuery)?,
+ lock_type: match row.get::<_, String>(3)?.as_str() {
+ "E" => PathLockKind::Exact,
+ "T" => PathLockKind::Tree,
+ _ => return Err(rusqlite::Error::InvalidQuery),
+ },
+ },
+ ))
+ },
+ )
+ .optional()
+ .map_err(db_error)?;
+ if let Some((path, token)) = found {
+ return Err(conflict(&path, &token));
+ }
+ }
+ let replacement = LockToken {
+ owner_id: owner.clone(),
+ time_ns: now_ns,
+ lock_type: request.kind,
+ };
+ let change = match existing {
+ Some(previous) if previous.owner_id == owner => {
+ if previous.lock_type == PathLockKind::Exact
+ && request.kind == PathLockKind::Tree
+ {
+ write(&tx, namespace, &request.path, &replacement)?;
+ AcquisitionChange::Upgraded {
+ previous,
+ replacement,
+ }
+ } else {
+ AcquisitionChange::Reentrant
+ }
+ }
+ _ => {
+ write(&tx, namespace, &request.path, &replacement)?;
+ AcquisitionChange::Created { replacement }
+ }
+ };
+ changes.push(AtomicAcquisition {
+ handle: request.path.clone(),
+ change,
+ });
+ }
+ tx.commit().map_err(db_error)?;
+ Ok(Some(AtomicAcquisitionResult {
+ acquisitions: changes,
+ stale_tokens_removed,
+ }))
+ })
+ .await
+ }
+
+ async fn rollback_acquisitions_atomic(
+ &self,
+ acquisitions: &[AtomicAcquisition],
+ owner_id: &str,
+ ) -> PathLockResult<Option<()>> {
+ let acquisitions = acquisitions.to_vec();
+ let owner = owner_id.to_string();
+ self.run(move |conn, namespace| {
+ let tx = conn
+ .transaction_with_behavior(TransactionBehavior::Immediate)
+ .map_err(db_error)?;
+ // Reverse order also handles repeated paths within a batch.
+ for acquisition in acquisitions.iter().rev() {
+ match &acquisition.change {
+ AcquisitionChange::Reentrant => {}
+ AcquisitionChange::Created { replacement }
+ | AcquisitionChange::Upgraded { replacement, .. }
+ if replacement.owner_id != owner =>
+ {
+ return Err(PathLockError::InvalidRequest(
+ "rollback owner mismatch".into(),
+ ));
+ }
+ AcquisitionChange::Created { replacement } => {
+ if read(&tx, namespace, &acquisition.handle)?.as_ref() != Some(replacement)
+ {
+ return Err(PathLockError::Internal("rollback token changed".into()));
+ }
+ tx.execute(
+ "DELETE FROM pathlock_tokens WHERE namespace=?1 AND path=?2",
+ params![namespace, acquisition.handle],
+ )
+ .map_err(db_error)?;
+ }
+ AcquisitionChange::Upgraded {
+ previous,
+ replacement,
+ } => {
+ if previous.owner_id != owner {
+ return Err(PathLockError::InvalidRequest(
+ "rollback previous owner mismatch".into(),
+ ));
+ }
+ if read(&tx, namespace, &acquisition.handle)?.as_ref() != Some(replacement)
+ {
+ return Err(PathLockError::Internal("rollback token changed".into()));
+ }
+ write(&tx, namespace, &acquisition.handle, previous)?;
+ }
+ }
+ }
+ tx.commit().map_err(db_error)?;
+ Ok(Some(()))
+ })
+ .await
+ }
+
+ async fn is_path_locked_atomic(
+ &self,
+ path: &str,
+ _now_ns: u128,
+ stale_before_ns: u128,
+ ignore_stale: bool,
+ ) -> PathLockResult<Option<bool>> {
+ validate_path(path)?;
+ let path = path.to_string();
+ self.run(move |conn, namespace| {
+ let tx = conn.transaction().map_err(db_error)?;
+ if read(&tx, namespace, &path)?
+ .is_some_and(|token| !ignore_stale || token.time_ns >= stale_before_ns)
+ {
+ return Ok(Some(true));
+ }
+ for ancestor in ancestors(&path) {
+ if read(&tx, namespace, ancestor)?.is_some_and(|token| {
+ token.lock_type == PathLockKind::Tree
+ && (!ignore_stale || token.time_ns >= stale_before_ns)
+ }) {
+ return Ok(Some(true));
+ }
+ }
+ Ok(Some(false))
+ })
+ .await
+ }
+
+ async fn read_token(&self, path: &str) -> PathLockResult<Option<LockToken>> {
+ let path = path.to_string();
+ self.run(move |conn, namespace| read(conn, namespace, &path))
+ .await
+ }
+
+ async fn try_create_token(&self, path: &str, token: &LockToken) -> PathLockResult<()> {
+ validate_path(path)?;
+ validate_owner(&token.owner_id)?;
+ let path = path.to_string();
+ let token = token.clone();
+ self.run(move |conn, namespace| {
+ let tx = conn
+ .transaction_with_behavior(TransactionBehavior::Immediate)
+ .map_err(db_error)?;
+ if let Some(existing) = read(&tx, namespace, &path)? {
+ return Err(conflict(&path, &existing));
+ }
+ write(&tx, namespace, &path, &token)?;
+ tx.commit().map_err(db_error)
+ })
+ .await
+ }
+
+ async fn compare_and_write_token(
+ &self,
+ path: &str,
+ expected: &LockToken,
+ replacement: &LockToken,
+ ) -> PathLockResult<bool> {
+ validate_path(path)?;
+ validate_owner(&replacement.owner_id)?;
+ let path = path.to_string();
+ let expected = expected.clone();
+ let replacement = replacement.clone();
+ self.run(move |conn, namespace| {
+ let tx = conn
+ .transaction_with_behavior(TransactionBehavior::Immediate)
+ .map_err(db_error)?;
+ let matched = read(&tx, namespace, &path)?.as_ref() == Some(&expected);
+ if matched {
+ write(&tx, namespace, &path, &replacement)?;
+ }
+ tx.commit().map_err(db_error)?;
+ Ok(matched)
+ })
+ .await
+ }
+
+ async fn refresh_token(&self, path: &str, owner: &str, time_ns: u128) -> PathLockResult<bool> {
+ let path = path.to_string();
+ let owner = owner.to_string();
+ self.run(move |conn, namespace| {
+ conn.execute(
+ "UPDATE pathlock_tokens SET time_ns=?1 WHERE namespace=?2 AND path=?3 AND owner=?4",
+ params![timestamp(time_ns), namespace, path, owner],
+ )
+ .map(|count| count == 1)
+ .map_err(db_error)
+ })
+ .await
+ }
+
+ async fn remove_token(&self, path: &str, owner: &str, _force: bool) -> PathLockResult<bool> {
+ let path = path.to_string();
+ let owner = owner.to_string();
+ self.run(move |conn, namespace| {
+ conn.execute(
+ "DELETE FROM pathlock_tokens WHERE namespace=?1 AND path=?2 AND owner=?3",
+ params![namespace, path, owner],
+ )
+ .map(|count| count == 1)
+ .map_err(db_error)
+ })
+ .await
+ }
+
+ async fn refresh_tokens(
+ &self,
+ paths: &[String],
+ owner: &str,
+ time_ns: u128,
+ ) -> Vec<PathLockResult<bool>> {
+ let validation: Vec<_> = paths.iter().map(|path| validate_path(path)).collect();
+ let valid_paths: Vec<_> = paths
+ .iter()
+ .zip(&validation)
+ .filter(|(_, result)| result.is_ok())
+ .map(|(path, _)| path.clone())
+ .collect();
+ if valid_paths.is_empty() {
+ return validation
+ .into_iter()
+ .map(|result| result.map(|_| false))
+ .collect();
+ }
+ let owner = owner.to_string();
+ // One worker and transaction per lease; bounded IN lists stay below SQLite
+ // parameter limits. RETURNING identifies each owned path without extra reads.
+ let result = self
+ .run(move |conn, namespace| {
+ let tx = conn
+ .transaction_with_behavior(TransactionBehavior::Immediate)
+ .map_err(db_error)?;
+ let mut refreshed = std::collections::HashSet::new();
+ for batch in valid_paths.chunks(256) {
+ let placeholders = vec!["?"; batch.len()].join(",");
+ let sql = format!(
+ "UPDATE pathlock_tokens SET time_ns=? WHERE namespace=? AND owner=?
+ AND path IN ({placeholders}) RETURNING path"
+ );
+ let mut args = vec![timestamp(time_ns), namespace.to_string(), owner.clone()];
+ args.extend_from_slice(batch);
+ let mut stmt = tx.prepare(&sql).map_err(db_error)?;
+ let rows = stmt
+ .query_map(rusqlite::params_from_iter(args), |row| {
+ row.get::<_, String>(0)
+ })
+ .map_err(db_error)?;
+ for row in rows {
+ refreshed.insert(row.map_err(db_error)?);
+ }
+ }
+ tx.commit().map_err(db_error)?;
+ Ok(refreshed)
+ })
+ .await;
+ paths
+ .iter()
+ .zip(validation)
+ .map(|(path, validation)| {
+ validation?;
+ match &result {
+ Ok(refreshed) => Ok(refreshed.contains(path)),
+ Err(PathLockError::Busy {
+ lock_path,
+ operation,
+ }) => Err(PathLockError::Busy {
+ lock_path: lock_path.clone(),
+ operation: operation.clone(),
+ }),
+ Err(error) => Err(PathLockError::Io(error.to_string())),
+ }
+ })
+ .collect()
+ }
+
+ async fn scan_descendant_locks(&self, root: &str) -> PathLockResult<Vec<String>> {
+ // Trait compatibility and diagnostics only: the manager's atomic acquisition
+ // hook returns early and never uses this fallback scan for SQLite.
+ validate_path(root)?;
+ let root = root.to_string();
+ self.run(move |conn, namespace| {
+ let (lower, upper) = descendant_bounds(&root);
+ let mut stmt = conn
+ .prepare(
+ "SELECT path FROM pathlock_tokens
+ WHERE namespace=?1 AND path>=?2 AND path<?3 AND path<>?4",
+ )
+ .map_err(db_error)?;
+ let rows = stmt
+ .query_map(params![namespace, lower, upper, root], |row| row.get(0))
+ .map_err(db_error)?;
+ rows.collect::<rusqlite::Result<Vec<_>>>().map_err(db_error)
+ })
+ .await
+ }
+}
+
+#[cfg(test)]
+#[path = "sqlite_provider_tests.rs"]
+mod tests;
diff --git a/crates/ragfs/src/lock/sqlite_provider_tests.rs b/crates/ragfs/src/lock/sqlite_provider_tests.rs
new file mode 100644
index 000000000..af5ae1bc8
--- /dev/null
+++ b/crates/ragfs/src/lock/sqlite_provider_tests.rs
@@ -0,0 +1,1146 @@
+use super::*;
+use crate::core::FileSystem;
+use crate::lock::{PathLockConfig, PathLockManager};
+use crate::plugins::memfs::MemFileSystem;
+use std::process::{Child, Command};
+use std::time::Instant;
+use tempfile::TempDir;
+
+fn provider(dir: &TempDir, namespace: &str) -> SQLitePathLockProvider {
+ SQLitePathLockProvider::new(dir.path().join("locks.db").to_str().unwrap(), namespace).unwrap()
+}
+
+fn request(path: &str, kind: PathLockKind) -> PathLockRequest {
+ PathLockRequest {
+ path: path.into(),
+ kind,
+ }
+}
+
+async fn acquire(
+ provider: &SQLitePathLockProvider,
+ path: &str,
+ kind: PathLockKind,
+ owner: &str,
+ now: u128,
+ stale: u128,
+) -> PathLockResult<Vec<AtomicAcquisition>> {
+ provider
+ .try_acquire_batch_atomic(&[request(path, kind)], owner, now, stale)
+ .await
+ .map(Option::unwrap)
+}
+
+#[tokio::test]
+async fn exact_and_tree_conflicts_are_shared_between_connections() {
+ let dir = TempDir::new().unwrap();
+ let first = provider(&dir, "test");
+ let second = provider(&dir, "test");
+ acquire(&first, "/a", PathLockKind::Exact, "one", 100, 0)
+ .await
+ .unwrap();
+ // An ancestor Exact does not cover its children.
+ acquire(&second, "/a/b", PathLockKind::Exact, "two", 100, 0)
+ .await
+ .unwrap();
+ assert!(matches!(
+ acquire(&second, "/a", PathLockKind::Tree, "two", 100, 0).await,
+ Err(PathLockError::Conflict { .. })
+ ));
+ assert!(
+ matches!(acquire(&first, "/a", PathLockKind::Tree, "one", 100, 0).await,
+ Err(PathLockError::Conflict { lock_path, .. }) if lock_path == "/a/b")
+ );
+ second.remove_token("/a/b", "two", false).await.unwrap();
+ acquire(&first, "/a", PathLockKind::Tree, "one", 101, 0)
+ .await
+ .unwrap();
+ assert!(matches!(
+ acquire(&second, "/a/b", PathLockKind::Exact, "two", 101, 0).await,
+ Err(PathLockError::Conflict {
+ kind: PathLockKind::Tree,
+ ..
+ })
+ ));
+ assert_eq!(
+ second
+ .is_path_locked_atomic("/a/b", 101, 0, true)
+ .await
+ .unwrap(),
+ Some(true)
+ );
+}
+
+#[tokio::test]
+async fn prefix_boundaries_wildcards_unicode_root_and_namespaces() {
+ let dir = TempDir::new().unwrap();
+ let locks = provider(&dir, "one");
+ for path in ["/ab/x", "/a%/x", "/a_/x", "/树/x", "/local/account2/x"] {
+ acquire(&locks, path, PathLockKind::Exact, "one", 100, 0)
+ .await
+ .unwrap();
+ }
+ for path in ["/a", "/a%", "/a_", "/树", "/local/account2"] {
+ let result = acquire(&locks, path, PathLockKind::Tree, "two", 100, 0).await;
+ if path == "/a" {
+ result.unwrap();
+ } else {
+ assert!(matches!(result, Err(PathLockError::Conflict { .. })));
+ }
+ }
+ assert!(locks.scan_descendant_locks("/a").await.unwrap().is_empty());
+ assert_eq!(locks.scan_descendant_locks("/").await.unwrap().len(), 6);
+ assert!(matches!(
+ acquire(&locks, "/", PathLockKind::Tree, "three", 100, 0).await,
+ Err(PathLockError::Conflict { .. })
+ ));
+ // Separate services in the same DB do not conflict; account paths remain distinct.
+ acquire(
+ &provider(&dir, "two"),
+ "/",
+ PathLockKind::Tree,
+ "three",
+ 100,
+ 0,
+ )
+ .await
+ .unwrap();
+ acquire(
+ &locks,
+ "/local/account1",
+ PathLockKind::Tree,
+ "three",
+ 100,
+ 0,
+ )
+ .await
+ .unwrap();
+}
+
+#[tokio::test]
+async fn stale_takeover_preserves_u128_boundary_and_ownership() {
+ let dir = TempDir::new().unwrap();
+ let locks = provider(&dir, "test");
+ acquire(&locks, "/a/b", PathLockKind::Exact, "old", u128::MAX - 1, 0)
+ .await
+ .unwrap();
+ assert!(matches!(
+ acquire(
+ &locks,
+ "/a",
+ PathLockKind::Tree,
+ "new",
+ u128::MAX,
+ u128::MAX - 1
+ )
+ .await,
+ Err(PathLockError::Conflict { .. })
+ ));
+ acquire(
+ &locks,
+ "/a",
+ PathLockKind::Tree,
+ "new",
+ u128::MAX,
+ u128::MAX,
+ )
+ .await
+ .unwrap();
+ assert_eq!(
+ locks.read_token("/a").await.unwrap().unwrap().time_ns,
+ u128::MAX
+ );
+ acquire(
+ &locks,
+ "/a/b",
+ PathLockKind::Exact,
+ "new",
+ u128::MAX,
+ u128::MAX,
+ )
+ .await
+ .unwrap();
+ assert!(!locks.refresh_token("/a/b", "old", 0).await.unwrap());
+ assert!(!locks.remove_token("/a/b", "old", true).await.unwrap());
+ assert!(locks.refresh_token("/a/b", "new", 9).await.unwrap());
+ assert_eq!(
+ locks
+ .is_path_locked_atomic("/a", u128::MAX, u128::MAX, true)
+ .await
+ .unwrap(),
+ Some(true)
+ );
+ locks.remove_token("/a", "new", false).await.unwrap();
+ assert_eq!(
+ locks
+ .is_path_locked_atomic("/a/b", 10, 10, true)
+ .await
+ .unwrap(),
+ Some(false)
+ );
+ assert_eq!(
+ locks
+ .is_path_locked_atomic("/a/b", 10, 10, false)
+ .await
+ .unwrap(),
+ Some(true)
+ );
+ // Decimal length changes must not reverse staleness.
+ assert!(matches!(
+ acquire(&locks, "/a/b", PathLockKind::Exact, "next", 10, 9).await,
+ Err(PathLockError::Conflict { .. })
+ ));
+ acquire(&locks, "/a/b", PathLockKind::Exact, "next", 10, 10)
+ .await
+ .unwrap();
+}
+
+#[tokio::test]
+async fn conflict_rolls_back_the_whole_batch_including_upgrades() {
+ let dir = TempDir::new().unwrap();
+ let locks = provider(&dir, "test");
+ acquire(&locks, "/a", PathLockKind::Exact, "one", 1, 0)
+ .await
+ .unwrap();
+ acquire(&locks, "/z", PathLockKind::Exact, "two", 1, 0)
+ .await
+ .unwrap();
+ let before = locks.read_token("/a").await.unwrap();
+ let result = locks
+ .try_acquire_batch_atomic(
+ &[
+ request("/a", PathLockKind::Tree),
+ request("/b", PathLockKind::Exact),
+ request("/z", PathLockKind::Exact),
+ ],
+ "one",
+ 2,
+ 0,
+ )
+ .await;
+ assert!(matches!(result, Err(PathLockError::Conflict { .. })));
+ assert_eq!(locks.read_token("/a").await.unwrap(), before);
+ assert_eq!(locks.read_token("/b").await.unwrap(), None);
+}
+
+#[tokio::test]
+async fn rollback_restores_upgrade_and_preserves_reentrant_tokens() {
+ let dir = TempDir::new().unwrap();
+ let locks = provider(&dir, "test");
+ acquire(&locks, "/a", PathLockKind::Exact, "one", 1, 0)
+ .await
+ .unwrap();
+ let before = locks.read_token("/a").await.unwrap();
+ let changes = locks
+ .try_acquire_batch_atomic(
+ &[
+ request("/a", PathLockKind::Exact),
+ request("/a", PathLockKind::Tree),
+ request("/b", PathLockKind::Exact),
+ request("/b", PathLockKind::Tree),
+ ],
+ "one",
+ 2,
+ 0,
+ )
+ .await
+ .unwrap()
+ .unwrap();
+ assert_eq!(changes[0].change, AcquisitionChange::Reentrant);
+ locks
+ .rollback_acquisitions_atomic(&changes, "one")
+ .await
+ .unwrap();
+ assert_eq!(locks.read_token("/a").await.unwrap(), before);
+ assert_eq!(locks.read_token("/b").await.unwrap(), None);
+}
+
+#[tokio::test]
+async fn changed_rollback_is_atomic_and_cas_checks_the_entire_token() {
+ let dir = TempDir::new().unwrap();
+ let locks = provider(&dir, "test");
+ let changes = locks
+ .try_acquire_batch_atomic(
+ &[
+ request("/a", PathLockKind::Exact),
+ request("/b", PathLockKind::Exact),
+ ],
+ "one",
+ 1,
+ 0,
+ )
+ .await
+ .unwrap()
+ .unwrap();
+ let expected = locks.read_token("/a").await.unwrap().unwrap();
+ assert!(locks.refresh_token("/a", "one", 2).await.unwrap());
+ assert!(!locks
+ .compare_and_write_token("/a", &expected, &expected)
+ .await
+ .unwrap());
+ assert!(locks
+ .rollback_acquisitions_atomic(&changes, "one")
+ .await
+ .is_err());
+ // /b was removed first, but the transaction must roll that deletion back.
+ assert!(locks.read_token("/b").await.unwrap().is_some());
+ let current = locks.read_token("/a").await.unwrap().unwrap();
+ assert!(locks
+ .compare_and_write_token("/a", &current, &expected)
+ .await
+ .unwrap());
+ locks
+ .rollback_acquisitions_atomic(&changes, "one")
+ .await
+ .unwrap();
+ assert!(locks.scan_descendant_locks("/").await.unwrap().is_empty());
+}
+
+#[tokio::test]
+async fn database_write_contention_is_retryable_busy() {
+ let dir = TempDir::new().unwrap();
+ let locks = provider(&dir, "test");
+ let mut blocker = Connection::open(dir.path().join("locks.db")).unwrap();
+ let tx = blocker
+ .transaction_with_behavior(TransactionBehavior::Immediate)
+ .unwrap();
+ let start = Instant::now();
+ assert!(matches!(
+ acquire(&locks, "/a", PathLockKind::Tree, "one", 1, 0).await,
+ Err(PathLockError::Busy { .. })
+ ));
+ assert!(start.elapsed() >= SQLITE_BUSY_TIMEOUT);
+ assert!(start.elapsed() < Duration::from_secs(3));
+ drop(tx);
+ acquire(&locks, "/a", PathLockKind::Tree, "one", 1, 0)
+ .await
+ .unwrap();
+}
+
+#[tokio::test]
+async fn run_retries_busy_from_clean_transactions_without_duplicate_mutations() {
+ let dir = TempDir::new().unwrap();
+ let locks = provider(&dir, "test");
+ acquire(&locks, "/old", PathLockKind::Exact, "dead", 1, 0)
+ .await
+ .unwrap();
+ let mut attempts = 0;
+ let result = locks
+ .run(move |conn, namespace| {
+ attempts += 1;
+ assert!(conn.is_autocommit());
+ let tx = conn
+ .transaction_with_behavior(TransactionBehavior::Immediate)
+ .map_err(db_error)?;
+ // Both mutations from each failed attempt must have rolled back.
+ assert!(read(&tx, namespace, "/old")?.is_some());
+ assert!(read(&tx, namespace, "/new")?.is_none());
+ let removed = tx
+ .execute(
+ "DELETE FROM pathlock_tokens WHERE namespace=?1 AND path='/old'",
+ params![namespace],
+ )
+ .map_err(db_error)?;
+ write(
+ &tx,
+ namespace,
+ "/new",
+ &LockToken {
+ owner_id: "new".into(),
+ time_ns: 2,
+ lock_type: PathLockKind::Tree,
+ },
+ )?;
+ if attempts < SQLITE_BUSY_ATTEMPTS {
+ return Err(PathLockError::Busy {
+ lock_path: "sqlite".into(),
+ operation: "injected after mutation".into(),
+ });
+ }
+ tx.commit().map_err(db_error)?;
+ Ok((attempts, removed))
+ })
+ .await
+ .unwrap();
+ assert_eq!(result, (SQLITE_BUSY_ATTEMPTS, 1));
+ assert!(locks.read_token("/old").await.unwrap().is_none());
+ assert_eq!(
+ locks.read_token("/new").await.unwrap().unwrap().owner_id,
+ "new"
+ );
+}
+
+#[tokio::test]
+async fn run_bounds_busy_attempts_and_does_not_retry_other_errors() {
+ use std::sync::atomic::{AtomicUsize, Ordering};
+ let dir = TempDir::new().unwrap();
+ let locks = provider(&dir, "test");
+ for kind in ["busy", "conflict", "invalid", "io"] {
+ let calls = Arc::new(AtomicUsize::new(0));
+ let observed = calls.clone();
+ let result: PathLockResult<()> = locks
+ .run(move |_, _| {
+ observed.fetch_add(1, Ordering::SeqCst);
+ Err(match kind {
+ "busy" => PathLockError::Busy {
+ lock_path: "sqlite".into(),
+ operation: "injected".into(),
+ },
+ "conflict" => PathLockError::Conflict {
+ lock_path: "/a".into(),
+ owner: "other".into(),
+ kind: PathLockKind::Tree,
+ },
+ "invalid" => PathLockError::InvalidRequest("injected".into()),
+ _ => PathLockError::Io("injected".into()),
+ })
+ })
+ .await;
+ assert_eq!(
+ calls.load(Ordering::SeqCst),
+ if kind == "busy" {
+ SQLITE_BUSY_ATTEMPTS
+ } else {
+ 1
+ }
+ );
+ assert!(matches!(
+ (kind, result),
+ ("busy", Err(PathLockError::Busy { .. }))
+ | ("conflict", Err(PathLockError::Conflict { .. }))
+ | ("invalid", Err(PathLockError::InvalidRequest(_)))
+ | ("io", Err(PathLockError::Io(_)))
+ ));
+ }
+}
+
+async fn with_transient_writer<T>(
+ blocker: &mut Connection,
+ operation: impl std::future::Future<Output = T>,
+) -> T {
+ let tx = blocker
+ .transaction_with_behavior(TransactionBehavior::Immediate)
+ .unwrap();
+ // Keep the writer longer than one busy timeout, then allow provider retries
+ // to recover. Tokio's timer also verifies waits stay off the async executor.
+ let (result, ()) = tokio::join!(operation, async {
+ tokio::time::sleep(SQLITE_BUSY_TIMEOUT + Duration::from_millis(50)).await;
+ drop(tx);
+ });
+ result
+}
+
+#[tokio::test]
+async fn busy_retries_cover_zero_timeout_acquire_refresh_release_and_rollback() {
+ let dir = TempDir::new().unwrap();
+ let locks = Arc::new(provider(&dir, "test"));
+ let manager = PathLockManager::new(
+ Arc::new(MemFileSystem::new()),
+ locks.clone(),
+ PathLockConfig::default(),
+ );
+ let mut blocker = Connection::open(dir.path().join("locks.db")).unwrap();
+ let lease = with_transient_writer(
+ &mut blocker,
+ manager.acquire_tree("/a", Duration::ZERO, None),
+ )
+ .await
+ .unwrap();
+ assert_eq!(
+ with_transient_writer(&mut blocker, manager.refresh(&lease))
+ .await
+ .unwrap(),
+ "refreshed"
+ );
+ assert!(with_transient_writer(
+ &mut blocker,
+ locks.refresh_token("/a", &lease.lease.owner_id, u128::MAX),
+ )
+ .await
+ .unwrap());
+ with_transient_writer(&mut blocker, manager.release(&lease))
+ .await
+ .unwrap();
+ assert!(locks.read_token("/a").await.unwrap().is_none());
+
+ let changes = acquire(&locks, "/rollback", PathLockKind::Tree, "owner", 1, 0)
+ .await
+ .unwrap();
+ with_transient_writer(
+ &mut blocker,
+ locks.rollback_acquisitions_atomic(&changes, "owner"),
+ )
+ .await
+ .unwrap();
+ assert!(locks.read_token("/rollback").await.unwrap().is_none());
+}
+
+#[tokio::test]
+async fn manager_zero_timeout_waits_for_transient_sqlite_writer() {
+ let dir = TempDir::new().unwrap();
+ let locks = Arc::new(provider(&dir, "test"));
+ let manager = PathLockManager::new(
+ Arc::new(MemFileSystem::new()),
+ locks.clone(),
+ PathLockConfig::default(),
+ );
+ let mut blocker = Connection::open(dir.path().join("locks.db")).unwrap();
+ let tx = blocker
+ .transaction_with_behavior(TransactionBehavior::Immediate)
+ .unwrap();
+ let (lease, ()) = tokio::join!(manager.acquire_tree("/a", Duration::ZERO, None), async {
+ tokio::time::sleep(Duration::from_millis(20)).await;
+ drop(tx);
+ });
+ let lease = lease.unwrap();
+ manager.release(&lease).await.unwrap();
+ assert!(locks.read_token("/a").await.unwrap().is_none());
+}
+
+#[tokio::test]
+async fn rejects_invalid_paths_and_owner_before_mutation() {
+ let dir = TempDir::new().unwrap();
+ let locks = provider(&dir, "test");
+ for path in ["relative", "/a/", "/a//b", "/a/../b", "/./a", "/a\0b"] {
+ assert!(matches!(
+ acquire(&locks, path, PathLockKind::Exact, "one", 1, 0).await,
+ Err(PathLockError::InvalidRequest(_))
+ ));
+ }
+ for owner in ["", "bad:owner"] {
+ assert!(matches!(
+ acquire(&locks, "/a", PathLockKind::Exact, owner, 1, 0).await,
+ Err(PathLockError::InvalidRequest(_))
+ ));
+ }
+ assert!(locks.scan_descendant_locks("/").await.unwrap().is_empty());
+ assert!(SQLitePathLockProvider::new(":memory:", "test").is_err());
+ assert!(
+ SQLitePathLockProvider::new(dir.path().join("other.db").to_str().unwrap(), "").is_err()
+ );
+}
+
+#[tokio::test]
+async fn manager_lifecycle_uses_logical_handles_and_never_reads_business_directories() {
+ let dir = TempDir::new().unwrap();
+ let fs = Arc::new(MemFileSystem::new());
+ let locks = Arc::new(provider(&dir, "test"));
+ let manager = PathLockManager::new(fs.clone(), locks.clone(), PathLockConfig::default());
+ let other = PathLockManager::new(
+ fs.clone(),
+ Arc::new(provider(&dir, "test")),
+ PathLockConfig::default(),
+ );
+ // This business directory does not exist. A filesystem scan would fail.
+ let exact = manager
+ .acquire_exact("/missing/file", Duration::ZERO, None)
+ .await
+ .unwrap();
+ assert_eq!(exact.lease.lock_paths, vec!["/missing/file"]);
+ assert!(other
+ .acquire_tree("/missing", Duration::ZERO, None)
+ .await
+ .is_err());
+ let tree = manager
+ .acquire_tree(
+ "/missing",
+ Duration::ZERO,
+ Some((&exact.lease.lease_ref, &exact.ownership_ref)),
+ )
+ .await
+ .unwrap();
+ assert!(other.is_locked("/missing/child", true).await.unwrap());
+ manager.release(&tree).await.unwrap();
+ manager.release(&exact).await.unwrap();
+ let tree = other
+ .acquire_tree("/missing", Duration::ZERO, None)
+ .await
+ .unwrap();
+ other.release(&tree).await.unwrap();
+ assert!(locks.scan_descendant_locks("/").await.unwrap().is_empty());
+ assert_eq!(
+ fs.read_dir("/", None, None, None, None)
+ .await
+ .unwrap()
+ .len(),
+ 0
+ );
+}
+
+#[tokio::test]
+async fn manager_upgrade_downgrades_and_handoff_adopts() {
+ let dir = TempDir::new().unwrap();
+ let locks = Arc::new(provider(&dir, "test"));
+ let fs = Arc::new(MemFileSystem::new());
+ let manager = PathLockManager::new(fs.clone(), locks.clone(), PathLockConfig::default());
+ let exact = manager
+ .acquire_exact("/a", Duration::ZERO, None)
+ .await
+ .unwrap();
+ let tree = manager
+ .acquire_tree(
+ "/a",
+ Duration::ZERO,
+ Some((&exact.lease.lease_ref, &exact.ownership_ref)),
+ )
+ .await
+ .unwrap();
+ manager.release(&tree).await.unwrap();
+ assert_eq!(
+ locks.read_token("/a").await.unwrap().unwrap().lock_type,
+ PathLockKind::Exact
+ );
+ let handoff = manager.to_handoff(&exact);
+ manager.handoff(&exact).await.unwrap();
+ let recipient = PathLockManager::new(
+ fs,
+ Arc::new(provider(&dir, "test")),
+ PathLockConfig::default(),
+ );
+ let adopted = recipient.adopt(&handoff).await.unwrap();
+ recipient.release(&adopted).await.unwrap();
+ assert_eq!(locks.read_token("/a").await.unwrap(), None);
+}
+
+#[tokio::test]
+async fn manager_refreshes_live_tokens() {
+ let dir = TempDir::new().unwrap();
+ let locks = Arc::new(provider(&dir, "test"));
+ let config = PathLockConfig {
+ lock_expire_secs: 1.0,
+ ..PathLockConfig::default()
+ };
+ let manager = PathLockManager::new(Arc::new(MemFileSystem::new()), locks.clone(), config);
+ let lease = manager
+ .acquire_tree("/a", Duration::ZERO, None)
+ .await
+ .unwrap();
+ let initial = locks.read_token("/a").await.unwrap().unwrap().time_ns;
+ tokio::time::timeout(Duration::from_secs(3), async {
+ loop {
+ if locks.read_token("/a").await.unwrap().unwrap().time_ns > initial {
+ break;
+ }
+ tokio::time::sleep(Duration::from_millis(20)).await;
+ }
+ })
+ .await
+ .unwrap();
+ manager.release(&lease).await.unwrap();
+}
+
+#[tokio::test]
+async fn stale_cleanup_is_bounded_and_keeps_this_owners_tokens() {
+ let dir = TempDir::new().unwrap();
+ let locks = provider(&dir, "test");
+ let requests: Vec<_> = (0..300)
+ .map(|id| request(&format!("/old/{id}"), PathLockKind::Exact))
+ .collect();
+ locks
+ .try_acquire_batch_atomic(&requests, "old", 1, 0)
+ .await
+ .unwrap();
+ acquire(&locks, "/own", PathLockKind::Exact, "new", 1, 0)
+ .await
+ .unwrap();
+ acquire(&locks, "/new", PathLockKind::Exact, "new", 2, 2)
+ .await
+ .unwrap();
+ assert_eq!(locks.scan_descendant_locks("/old").await.unwrap().len(), 44);
+ assert!(locks.read_token("/own").await.unwrap().is_some());
+ acquire(&locks, "/new", PathLockKind::Exact, "new", 3, 2)
+ .await
+ .unwrap();
+ assert!(locks
+ .scan_descendant_locks("/old")
+ .await
+ .unwrap()
+ .is_empty());
+}
+
+#[tokio::test]
+async fn stale_conflicting_descendants_cannot_be_revived_after_tree_takeover() {
+ for root in ["/a", "/"] {
+ let dir = TempDir::new().unwrap();
+ let old = provider(&dir, "test");
+ let new = provider(&dir, "test");
+ let requests: Vec<_> = (0..300)
+ .map(|id| {
+ request(
+ &format!("{}/child/{id:03}", root.trim_end_matches('/')),
+ if id % 2 == 0 {
+ PathLockKind::Exact
+ } else {
+ PathLockKind::Tree
+ },
+ )
+ })
+ .collect();
+ old.try_acquire_batch_atomic(&requests, "old", 1, 0)
+ .await
+ .unwrap();
+ let result = new
+ .try_acquire_batch_atomic_with_stats(&[request(root, PathLockKind::Tree)], "new", 10, 2)
+ .await
+ .unwrap()
+ .unwrap();
+ let paths: Vec<_> = requests
+ .iter()
+ .map(|request| request.path.clone())
+ .collect();
+ let refreshed = old.refresh_tokens(&paths, "old", 11).await;
+ assert!(
+ refreshed.iter().all(|result| matches!(result, Ok(false))),
+ "expired descendants must not revive under {root}: {refreshed:?}"
+ );
+ assert_eq!(result.stale_tokens_removed, 300);
+ assert!(!old.refresh_token(&paths[299], "old", 12).await.unwrap());
+ assert!(new.scan_descendant_locks(root).await.unwrap().is_empty());
+ assert_eq!(new.read_token(root).await.unwrap().unwrap().owner_id, "new");
+ assert!(matches!(
+ acquire(&old, &paths[299], PathLockKind::Exact, "old", 12, 2).await,
+ Err(PathLockError::Conflict {
+ kind: PathLockKind::Tree,
+ ..
+ })
+ ));
+ }
+}
+
+#[tokio::test]
+async fn stale_target_and_ancestor_trees_are_cleaned_beyond_unrelated_budget() {
+ let dir = TempDir::new().unwrap();
+ let old = provider(&dir, "test");
+ let new = provider(&dir, "test");
+ let unrelated: Vec<_> = (0..300)
+ .map(|id| request(&format!("/unrelated/{id:03}"), PathLockKind::Exact))
+ .collect();
+ old.try_acquire_batch_atomic(&unrelated, "old", 0, 0)
+ .await
+ .unwrap();
+ let conflicting = [
+ request("/", PathLockKind::Tree),
+ request("/a", PathLockKind::Tree),
+ request("/a/b/c", PathLockKind::Exact),
+ ];
+ old.try_acquire_batch_atomic(&conflicting, "old", 1, 0)
+ .await
+ .unwrap();
+ acquire(&old, "/a/b", PathLockKind::Exact, "old", 1, 0)
+ .await
+ .unwrap();
+ // A separate namespace survives the cleanup.
+ let other = provider(&dir, "other");
+ acquire(&other, "/", PathLockKind::Tree, "old", 1, 0)
+ .await
+ .unwrap();
+ let result = new
+ .try_acquire_batch_atomic_with_stats(
+ &[request("/a/b/c", PathLockKind::Exact)],
+ "new",
+ 10,
+ 2,
+ )
+ .await
+ .unwrap()
+ .unwrap();
+ assert_eq!(result.stale_tokens_removed, 259);
+ let paths: Vec<_> = conflicting
+ .iter()
+ .map(|request| request.path.clone())
+ .collect();
+ assert!(old
+ .refresh_tokens(&paths, "old", 11)
+ .await
+ .iter()
+ .all(|result| matches!(result, Ok(false))));
+ assert_eq!(
+ old.scan_descendant_locks("/unrelated").await.unwrap().len(),
+ 44
+ );
+ assert!(old.refresh_token("/a/b", "old", 11).await.unwrap());
+ assert!(other.refresh_token("/", "old", 11).await.unwrap());
+}
+
+#[tokio::test]
+async fn failed_batch_restores_stale_conflicts_beyond_cleanup_budget() {
+ let dir = TempDir::new().unwrap();
+ let old = provider(&dir, "test");
+ let new = provider(&dir, "test");
+ let requests: Vec<_> = (0..300)
+ .map(|id| request(&format!("/a/{id:03}"), PathLockKind::Exact))
+ .collect();
+ old.try_acquire_batch_atomic(&requests, "old", 1, 0)
+ .await
+ .unwrap();
+ acquire(&old, "/live", PathLockKind::Exact, "live", 10, 0)
+ .await
+ .unwrap();
+ assert!(matches!(
+ new.try_acquire_batch_atomic_with_stats(
+ &[
+ request("/a", PathLockKind::Tree),
+ request("/live", PathLockKind::Exact),
+ ],
+ "new",
+ 10,
+ 2,
+ )
+ .await,
+ Err(PathLockError::Conflict { .. })
+ ));
+ assert!(new.read_token("/a").await.unwrap().is_none());
+ assert_eq!(old.scan_descendant_locks("/a").await.unwrap().len(), 300);
+ let paths: Vec<_> = requests
+ .iter()
+ .map(|request| request.path.clone())
+ .collect();
+ assert!(old
+ .refresh_tokens(&paths, "old", 11)
+ .await
+ .iter()
+ .all(|result| matches!(result, Ok(true))));
+}
+
+fn wait_for_file(path: &Path) {
+ let start = Instant::now();
+ while !path.exists() {
+ assert!(
+ start.elapsed() < Duration::from_secs(15),
+ "timed out waiting for {path:?}"
+ );
+ std::thread::sleep(Duration::from_millis(5));
+ }
+}
+
+#[tokio::test]
+async fn batch_refresh_preserves_order_ownership_kinds_and_large_batches() {
+ let dir = TempDir::new().unwrap();
+ let locks = provider(&dir, "test");
+ let requests: Vec<_> = (0..600)
+ .map(|id| {
+ request(
+ &format!("/batch/{id}"),
+ if id % 2 == 0 {
+ PathLockKind::Tree
+ } else {
+ PathLockKind::Exact
+ },
+ )
+ })
+ .collect();
+ locks
+ .try_acquire_batch_atomic(&requests, "one", 1, 0)
+ .await
+ .unwrap();
+ acquire(&locks, "/foreign", PathLockKind::Exact, "two", 1, 0)
+ .await
+ .unwrap();
+ let mut paths: Vec<_> = requests
+ .iter()
+ .map(|request| request.path.clone())
+ .collect();
+ paths.extend([
+ "/missing".into(),
+ "/foreign".into(),
+ "invalid".into(),
+ "/batch/0".into(),
+ ]);
+ let results = locks.refresh_tokens(&paths, "one", u128::MAX).await;
+ assert_eq!(results.len(), paths.len());
+ assert!(results[..600]
+ .iter()
+ .all(|result| matches!(result, Ok(true))));
+ assert!(matches!(results[600], Ok(false)));
+ assert!(matches!(results[601], Ok(false)));
+ assert!(matches!(
+ results[602],
+ Err(PathLockError::InvalidRequest(_))
+ ));
+ assert!(matches!(results[603], Ok(true)));
+ for request in requests {
+ let token = locks.read_token(&request.path).await.unwrap().unwrap();
+ assert_eq!(token.time_ns, u128::MAX);
+ assert_eq!(token.lock_type, request.kind);
+ }
+ assert_eq!(
+ locks.read_token("/foreign").await.unwrap().unwrap().time_ns,
+ 1
+ );
+ assert!(locks.refresh_tokens(&[], "one", 2).await.is_empty());
+}
+
+#[tokio::test]
+async fn batch_refresh_reports_busy_for_every_path_and_does_not_partially_commit() {
+ let dir = TempDir::new().unwrap();
+ let locks = provider(&dir, "test");
+ acquire(&locks, "/a", PathLockKind::Exact, "one", 1, 0)
+ .await
+ .unwrap();
+ acquire(&locks, "/b", PathLockKind::Exact, "one", 1, 0)
+ .await
+ .unwrap();
+ let mut blocker = Connection::open(dir.path().join("locks.db")).unwrap();
+ let tx = blocker
+ .transaction_with_behavior(TransactionBehavior::Immediate)
+ .unwrap();
+ let results = locks
+ .refresh_tokens(&["/a".into(), "/b".into()], "one", 2)
+ .await;
+ assert!(results
+ .iter()
+ .all(|result| matches!(result, Err(PathLockError::Busy { .. }))));
+ drop(tx);
+ assert_eq!(locks.read_token("/a").await.unwrap().unwrap().time_ns, 1);
+ assert_eq!(locks.read_token("/b").await.unwrap().unwrap().time_ns, 1);
+}
+
+#[tokio::test]
+async fn atomic_recovery_counts_committed_cleanup_and_stale_replacements_once() {
+ let dir = TempDir::new().unwrap();
+ let locks = provider(&dir, "test");
+ let requests: Vec<_> = (0..300)
+ .map(|id| request(&format!("/old/{id:03}"), PathLockKind::Exact))
+ .collect();
+ locks
+ .try_acquire_batch_atomic(&requests, "old", 1, 0)
+ .await
+ .unwrap();
+ let result = locks
+ .try_acquire_batch_atomic_with_stats(
+ &[request("/old/299", PathLockKind::Tree)],
+ "new",
+ 10,
+ 2,
+ )
+ .await
+ .unwrap()
+ .unwrap();
+ assert_eq!(result.stale_tokens_removed, 257);
+ let result = locks
+ .try_acquire_batch_atomic_with_stats(
+ &[request("/old/299", PathLockKind::Tree)],
+ "new",
+ 10,
+ 2,
+ )
+ .await
+ .unwrap()
+ .unwrap();
+ assert_eq!(result.stale_tokens_removed, 43);
+ let result = locks
+ .try_acquire_batch_atomic_with_stats(
+ &[request("/old/299", PathLockKind::Tree)],
+ "new",
+ 10,
+ 2,
+ )
+ .await
+ .unwrap()
+ .unwrap();
+ assert_eq!(result.stale_tokens_removed, 0);
+}
+
+#[tokio::test]
+async fn manager_observes_only_committed_stale_recovery() {
+ let dir = TempDir::new().unwrap();
+ let locks = Arc::new(provider(&dir, "test"));
+ acquire(&locks, "/old", PathLockKind::Exact, "dead", 1, 0)
+ .await
+ .unwrap();
+ acquire(&locks, "/live", PathLockKind::Exact, "live", u128::MAX, 0)
+ .await
+ .unwrap();
+ let manager = PathLockManager::new(
+ Arc::new(MemFileSystem::new()),
+ locks.clone(),
+ PathLockConfig::default(),
+ );
+ assert!(manager
+ .acquire_exact("/live", Duration::ZERO, None)
+ .await
+ .is_err());
+ assert_eq!(manager.observe().await.stale_locks_removed, 0);
+ assert!(locks.read_token("/old").await.unwrap().is_some());
+ let lease = manager
+ .acquire_tree("/old", Duration::ZERO, None)
+ .await
+ .unwrap();
+ assert_eq!(manager.observe().await.stale_locks_removed, 1);
+ manager.release(&lease).await.unwrap();
+}
+
+// Kill only subprocesses started by this test if a failed assertion unwinds.
+struct Contender(Child);
+impl Drop for Contender {
+ fn drop(&mut self) {
+ let _ = self.0.kill();
+ let _ = self.0.wait();
+ }
+}
+
+#[test]
+fn separate_processes_cannot_acquire_tree_and_descendant_simultaneously() {
+ let dir = TempDir::new().unwrap();
+ drop(provider(&dir, "test"));
+ for (left, right, successes) in [
+ ("/a", "/a/b", 1),
+ ("/", "/a/b", 1),
+ ("/a", "/a", 1),
+ ("/a", "/b", 2),
+ ] {
+ let round = dir.path().join(uuid::Uuid::new_v4().to_string());
+ std::fs::create_dir(&round).unwrap();
+ let mut children = Vec::new();
+ for (id, path, kind) in [("left", left, "T"), ("right", right, "E")] {
+ let child = Command::new(std::env::current_exe().unwrap())
+ .args([
+ "--exact",
+ "lock::sqlite_provider::tests::subprocess_contender",
+ "--ignored",
+ "--nocapture",
+ ])
+ .env("OV_SQLITE_TEST_DIR", dir.path())
+ .env("OV_SQLITE_TEST_ROUND", &round)
+ .env("OV_SQLITE_TEST_ID", id)
+ .env("OV_SQLITE_TEST_PATH", path)
+ .env("OV_SQLITE_TEST_KIND", kind)
+ .spawn()
+ .unwrap();
+ children.push(Contender(child));
+ }
+ wait_for_file(&round.join("left.ready"));
+ wait_for_file(&round.join("right.ready"));
+ std::fs::write(round.join("go"), "").unwrap();
+ wait_for_file(&round.join("left.result"));
+ wait_for_file(&round.join("right.result"));
+ let results: Vec<_> = ["left", "right"]
+ .iter()
+ .map(|id| std::fs::read_to_string(round.join(format!("{id}.result"))).unwrap())
+ .collect();
+ std::fs::write(round.join("release"), "").unwrap();
+ for child in &mut children {
+ assert!(child.0.wait().unwrap().success());
+ }
+ assert_eq!(
+ results
+ .iter()
+ .filter(|result| *result == "acquired")
+ .count(),
+ successes
+ );
+ assert_eq!(
+ results
+ .iter()
+ .filter(|result| *result == "conflict")
+ .count(),
+ 2 - successes
+ );
+ }
+}
+
+#[test]
+fn crashed_process_token_is_persistent_and_can_be_reclaimed() {
+ let dir = TempDir::new().unwrap();
+ drop(provider(&dir, "test"));
+ let round = dir.path().join("crash");
+ std::fs::create_dir(&round).unwrap();
+ std::fs::write(round.join("go"), "").unwrap();
+ let mut child = Contender(
+ Command::new(std::env::current_exe().unwrap())
+ .args([
+ "--exact",
+ "lock::sqlite_provider::tests::subprocess_contender",
+ "--ignored",
+ ])
+ .env("OV_SQLITE_TEST_DIR", dir.path())
+ .env("OV_SQLITE_TEST_ROUND", &round)
+ .env("OV_SQLITE_TEST_ID", "crashed")
+ .env("OV_SQLITE_TEST_PATH", "/a/b")
+ .env("OV_SQLITE_TEST_KIND", "E")
+ .env("OV_SQLITE_TEST_CRASH", "1")
+ .spawn()
+ .unwrap(),
+ );
+ wait_for_file(&round.join("crashed.result"));
+ assert!(child.0.wait().unwrap().success());
+ let locks = provider(&dir, "test");
+ let runtime = tokio::runtime::Runtime::new().unwrap();
+ assert!(matches!(
+ runtime.block_on(acquire(&locks, "/a", PathLockKind::Tree, "next", 101, 100)),
+ Err(PathLockError::Conflict { .. })
+ ));
+ runtime
+ .block_on(acquire(&locks, "/a", PathLockKind::Tree, "next", 101, 101))
+ .unwrap();
+ assert!(
+ runtime
+ .block_on(locks.remove_token("/a/b", "crashed", false))
+ .unwrap()
+ == false
+ );
+}
+
+#[test]
+#[ignore = "subprocess helper invoked by separate_processes test"]
+fn subprocess_contender() {
+ let dir = std::path::PathBuf::from(std::env::var("OV_SQLITE_TEST_DIR").unwrap());
+ let round = std::path::PathBuf::from(std::env::var("OV_SQLITE_TEST_ROUND").unwrap());
+ let id = std::env::var("OV_SQLITE_TEST_ID").unwrap();
+ let path = std::env::var("OV_SQLITE_TEST_PATH").unwrap();
+ let kind = if std::env::var("OV_SQLITE_TEST_KIND").unwrap() == "T" {
+ PathLockKind::Tree
+ } else {
+ PathLockKind::Exact
+ };
+ let locks =
+ SQLitePathLockProvider::new(dir.join("locks.db").to_str().unwrap(), "test").unwrap();
+ let runtime = tokio::runtime::Runtime::new().unwrap();
+ std::fs::write(round.join(format!("{id}.ready")), "").unwrap();
+ wait_for_file(&round.join("go"));
+ if std::env::var_os("OV_SQLITE_TEST_CRASH").is_some() {
+ runtime
+ .block_on(acquire(&locks, &path, kind, &id, 100, 0))
+ .unwrap();
+ std::fs::write(round.join(format!("{id}.result")), "acquired").unwrap();
+ // Skip connection/runtime destructors as with an abruptly terminated owner.
+ std::process::exit(0);
+ }
+ let manager = runtime.block_on(async {
+ PathLockManager::new(
+ Arc::new(MemFileSystem::new()),
+ Arc::new(locks),
+ PathLockConfig::default(),
+ )
+ });
+ // Exercise the production path with the configured zero logical wait timeout.
+ // No test-side Busy retry may hide a transient database contention failure.
+ let lease = match runtime.block_on(manager.acquire_batch(
+ &[request(&path, kind)],
+ Duration::ZERO,
+ None,
+ )) {
+ Ok(lease) => Some(lease),
+ Err(PathLockError::Timeout { .. }) => {
+ assert!(
+ !runtime.block_on(manager.observe()).conflicts.is_empty(),
+ "zero-timeout acquisition failed without an actual logical lock conflict"
+ );
+ None
+ }
+ Err(error) => panic!("{error}"),
+ };
+ std::fs::write(
+ round.join(format!("{id}.result")),
+ if lease.is_some() {
+ "acquired"
+ } else {
+ "conflict"
+ },
+ )
+ .unwrap();
+ wait_for_file(&round.join("release"));
+ if let Some(lease) = lease {
+ runtime.block_on(manager.release(&lease)).unwrap();
+ }
+}
diff --git a/docs/en/concepts/09-transaction.md b/docs/en/concepts/09-transaction.md
index b6dd0b83b..a61751936 100644
--- a/docs/en/concepts/09-transaction.md
+++ b/docs/en/concepts/09-transaction.md
@@ -440,9 +440,15 @@ Redis-backed configuration:
| Parameter | Type | Description | Default |
|-----------|------|-------------|---------|
-| `provider` | str | `filesystem`, `memory`, or `cache` | `filesystem` |
+| `provider` | str | `filesystem`, `memory`, `sqlite`, or `cache` | `filesystem` |
+| `sqlite_path` | str / null | Optional absolute local database path for `sqlite`; see [SQLite setup](../configuration/01-server.md#storage) | `{storage.workspace}/_system/pathlock/pathlock.db` for `sqlite` |
| `lock_expire_secs` | float | Seconds before an unrefreshed lock becomes stale | `30.0` |
+For replicas sharing EFS across containers or hosts, use `provider="cache"` with
+shared Redis. SQLite is limited to one shared database file on the same machine's
+local disk; EFS/NFS/SMB and independent container-local databases are unsupported.
+See [deployment limits and provider selection](../configuration/01-server.md#storage).
+
Legacy compatibility form:
```json
diff --git a/docs/en/configuration/01-server.md b/docs/en/configuration/01-server.md
index 3c6923dae..17be9c1a5 100644
--- a/docs/en/configuration/01-server.md
+++ b/docs/en/configuration/01-server.md
@@ -303,12 +303,65 @@ Search and Find requests default to `limit: 10`; override the limit on each API
|---|---|---|---|
| `workspace` | path | `"./data"` | OpenViking workspace |
| `agfs.backend` | `local`, `memory`, `s3` | `local` | File and metadata backend |
+| `agfs.pathlock.provider` | `filesystem`, `memory`, `sqlite`, `cache` | `filesystem` | Path lock storage |
+| `agfs.pathlock.sqlite_path` | absolute local file path | `{workspace}/_system/pathlock/pathlock.db` for `sqlite` | Shared SQLite lock database; optional override |
| `vectordb.backend` | `local`, `cuvs`, `http`, `volcengine`, `vikingdb` | `local` | Vector database backend |
| `vectordb.dimension` | integer | follows Embedding | Vector collection dimension |
| `parse_output.mode` | `agfs`, `local` | `agfs` | Backend for intermediate parser artifacts |
| `parse_output.local_root` | path or `null` | system temp directory | Root directory used by local parser artifacts |
| `skip_process_lock` | boolean | `false` | Skip the workspace process lock; use only when accepting concurrent-write risk |
+For same-machine path locking on a local disk without recursive business-directory scans, set
+`storage.agfs.pathlock` to `{"provider":"sqlite"}`. The database defaults to
+`{storage.workspace}/_system/pathlock/pathlock.db`, resolved to an absolute path
+from the final workspace when initializing the runtime binding. An explicit absolute
+`sqlite_path` takes precedence. The database parent directory is created automatically.
+Omitting `sqlite_path` or setting it to `null` also uses this default when constructing
+`RAGFSBindingClient(config_path=..., config={"service_name": ...})` directly.
+Every participating process must access the same actual local database file,
+with the same top-level `service_name` and lock expiry setting. Containers on the
+same host must share that local file; identical paths in separate container
+filesystems refer to independent databases and do not coordinate locks.
+SQLite stores authoritative lock tokens and atomically checks Exact/Tree conflicts
+using its path index. Blocking database work runs off the async executor.
+SQLite waits up to 100 ms per attempt for transient database writer contention,
+including when the logical lock wait timeout is zero. The provider retries only
+Busy, with three total attempts and 1 ms / 4 ms backoff. Database waits can total
+about 300 ms, plus 5 ms backoff and execution/scheduling overhead. Exhausted
+retries still report Busy to the manager; logical lock Conflict is not retried. WAL uses
+`synchronous=FULL` to preserve committed lock tokens after a crash, at the cost of
+additional synchronization I/O compared with `NORMAL`.
+Lease heartbeats refresh owned paths in one SQLite transaction (bounded batches
+for large leases). `stale_locks_removed` includes tokens recovered by committed
+atomic SQLite/Redis acquisitions; failed transactions do not increment the count.
+
+SQLite acquisitions completely delete expired tokens belonging to other owners
+that conflict with the request: the target path, ancestor Tree locks, and all
+descendants of a requested Tree lock. Cleanup and acquisition share one transaction,
+so a previous owner cannot revive these tokens by refreshing them after takeover.
+Opportunistic global cleanup is limited to 256 tokens per acquisition; conflicting
+cleanup can exceed that limit and costs more for large expired subtrees.
+
+Do not place the database on EFS, NFS, or SMB. SQLite WAL requires participants
+on the same machine and is not supported on network filesystems; frequent lock
+updates also add synchronization I/O. If `storage.workspace` is on EFS, the
+default database path is on EFS too. Moving it to each container's local disk
+creates independent lock authorities and cannot coordinate replicas.
+
+For multiple containers or hosts sharing EFS, use shared Redis PathLock:
+set `storage.agfs.pathlock.provider="cache"` and top-level `cache.provider="redis"`.
+All replicas must use the same Redis deployment, top-level `service_name`, and
+lock expiry setting. See the [shared Redis configuration example](../guides/01-configuration.md).
+Shared QueueFS must also use a backend suitable for that deployment, such as
+`storage.agfs.queuefs.backend="cache"`; changing PathLock alone does not change
+the default SQLite queue backend.
+
+Stop all participating processes before switching providers:
+SQLite and filesystem lock files do not share a protocol. Do not delete the database,
+WAL, or SHM files while participants are running. Crashed owners' tokens become
+eligible for takeover after `lock_expire_secs` (default 30 seconds). This setting
+does not change the workspace process lock or other backend concurrency constraints.
+
Remote backends also require endpoint, bucket/collection, credentials, and timeout fields. See [Configuration](../guides/01-configuration.md#storage) for complete examples.
`parse_output.mode=local` avoids writing parser intermediates to shared AGFS.
diff --git a/docs/en/guides/01-configuration.md b/docs/en/guides/01-configuration.md
index e1d0f6847..6e07b34aa 100644
--- a/docs/en/guides/01-configuration.md
+++ b/docs/en/guides/01-configuration.md
@@ -1445,10 +1445,21 @@ The top-level `cache` section is a sibling of `storage`. Its public shape is Pro
| Parameter | Type | Description | Default |
|-----------|------|-------------|---------|
-| `provider` | str | `filesystem`, `memory`, or `cache`; `cache` uses the shared Redis CacheRuntime | `filesystem` |
+| `provider` | str | `filesystem`, `memory`, `sqlite`, or `cache`; `cache` uses the shared Redis CacheRuntime | `filesystem` |
+| `sqlite_path` | str / null | Optional absolute local shared lock database path. See [local SQLite setup](../configuration/01-server.md#storage) | `{storage.workspace}/_system/pathlock/pathlock.db` for `sqlite` |
| `lock_expire_secs` | float | Seconds before an unrefreshed lock becomes stale; must be at least `1.0` | `30.0` |
| `lock_timeout_secs` | float | Deprecated and ignored; runtime wait timeout remains `0.0` | `0.0` |
+SQLite PathLock is limited to processes sharing one actual database file on the
+same machine's local disk. Do not put it on EFS/NFS/SMB or give each replica its
+own container-local database. A workspace on EFS also puts the default
+`sqlite_path` on EFS. See [SQLite deployment limits](../configuration/01-server.md#storage).
+
+For multiple containers or hosts sharing EFS, use shared Redis PathLock as in
+the example below. All replicas must use the same Redis deployment, top-level
+`service_name`, and lock expiry setting. The example also uses Redis QueueFS
+so its default SQLite database is not placed on EFS.
+
```json
{
"service_name": "production",
diff --git a/docs/en/guides/14-ragfs-cache.md b/docs/en/guides/14-ragfs-cache.md
index f71a3db47..1a8b04d2a 100644
--- a/docs/en/guides/14-ragfs-cache.md
+++ b/docs/en/guides/14-ragfs-cache.md
@@ -165,7 +165,7 @@ The top-level `cache` section is a sibling of `storage`:
| Option | Type | Default | Description |
|--------|------|---------|-------------|
-| `provider` | str | `"filesystem"` | `filesystem`, `memory`, or `cache` |
+| `provider` | str | `"filesystem"` | `filesystem`, `memory`, `sqlite`, or `cache`; see [SQLite setup](../configuration/01-server.md#storage) |
| `lock_expire_secs` | float | `30.0` | Lock stale timeout; must be at least `1.0` |
Redis configuration:
diff --git a/docs/zh/concepts/09-transaction.md b/docs/zh/concepts/09-transaction.md
index 5d51ac49a..348f3d66d 100644
--- a/docs/zh/concepts/09-transaction.md
+++ b/docs/zh/concepts/09-transaction.md
@@ -448,9 +448,14 @@ Redis 配置:
| 参数 | 类型 | 说明 | 默认值 |
|------|------|------|--------|
-| `provider` | str | `filesystem`、`memory` 或 `cache` | `filesystem` |
+| `provider` | str | `filesystem`、`memory`、`sqlite` 或 `cache` | `filesystem` |
+| `sqlite_path` | str / null | 使用 `sqlite` 时可覆盖本地数据库绝对路径;见 [SQLite 配置](../configuration/01-server.md#storage) | 使用 `sqlite` 时为 `{storage.workspace}/_system/pathlock/pathlock.db` |
| `lock_expire_secs` | float | 未刷新的锁进入 stale 状态前的秒数 | `30.0` |
+跨容器或主机共享 EFS 的副本应使用 `provider="cache"`,连接共享 Redis。
+SQLite 仅支持同机共享同一个本地磁盘数据库文件,不支持 EFS/NFS/SMB
+或各容器独立的本地数据库。参见[部署限制与 Provider 选择](../configuration/01-server.md#storage)。
+
兼容旧写法:
```json
diff --git a/docs/zh/configuration/01-server.md b/docs/zh/configuration/01-server.md
index e064f4db1..c134e06aa 100644
--- a/docs/zh/configuration/01-server.md
+++ b/docs/zh/configuration/01-server.md
@@ -295,12 +295,58 @@ Search 和 Find 请求的默认 `limit` 为 `10`,可以在每次 API 或 SDK
|---|---|---|---|
| `workspace` | path | `"./data"` | OpenViking 工作目录 |
| `agfs.backend` | `local`、`memory`、`s3` | `local` | 文件与元数据存储后端 |
+| `agfs.pathlock.provider` | `filesystem`、`memory`、`sqlite`、`cache` | `filesystem` | 路径锁存储 |
+| `agfs.pathlock.sqlite_path` | 本地文件绝对路径 | 使用 `sqlite` 时为 `{workspace}/_system/pathlock/pathlock.db` | SQLite 共享锁数据库,可显式覆盖 |
| `vectordb.backend` | `local`、`cuvs`、`http`、`volcengine`、`vikingdb` | `local` | 向量数据库后端 |
| `vectordb.dimension` | integer | 跟随 Embedding | 向量集合维度 |
| `parse_output.mode` | `agfs`、`local` | `agfs` | parser 中间产物的存储后端 |
| `parse_output.local_root` | 路径或 `null` | 系统临时目录 | local parser artifact 的根目录 |
| `skip_process_lock` | boolean | `false` | 是否跳过 workspace 进程锁;仅在明确接受并发写风险时启用 |
+同机本地磁盘上的路径锁可通过 SQLite 避免递归扫描业务目录。将 `storage.agfs.pathlock` 设置为
+`{"provider":"sqlite"}`。数据库默认位于
+`{storage.workspace}/_system/pathlock/pathlock.db`,初始化运行时 binding 时
+根据最终 workspace 解析为绝对路径。显式指定的绝对路径 `sqlite_path` 优先,
+数据库父目录会自动创建。
+直接通过 `RAGFSBindingClient(config_path=..., config={"service_name": ...})` 构造时,
+省略 `sqlite_path` 或将其设为 `null` 也会使用上述默认路径。
+所有参与进程必须访问同一个实际的本地数据库文件,并使用相同的顶层 `service_name` 和锁过期配置。
+同一主机上的容器必须共享该本地文件;不同容器文件系统中相同的路径字符串指向独立数据库,
+不能互相协调路径锁。
+SQLite 是锁状态的唯一存储,通过路径索引查询,并在事务中原子检查及获取 Exact/Tree 锁;
+数据库阻塞操作在异步执行器之外运行。
+SQLite 每次尝试对瞬时数据库写竞争最多等待 100 毫秒,即使逻辑锁等待超时为零也会执行该等待。
+仅 Busy 会在 provider 内重试,最多尝试 3 次,重试前分别退避 1、4 毫秒;
+数据库等待可累计约 300 毫秒,另加 5 毫秒退避及执行、调度开销。
+重试耗尽仍向 manager 返回 Busy;逻辑锁 Conflict 不重试。
+WAL 使用 `synchronous=FULL` 保证崩溃后已提交锁记录的持久性,
+代价是比 `NORMAL` 更多的同步 I/O。
+租约心跳在一次 SQLite 事务中批量刷新所属路径,大租约按有限大小分批执行。
+`stale_locks_removed` 包含 SQLite/Redis 原子加锁事务实际回收的锁数量,
+失败并回滚的事务不会增加计数。
+
+SQLite 加锁会完整删除其他 owner 持有、已过期且与本次请求冲突的记录:
+目标路径、祖先 Tree 锁,以及请求 Tree 锁时的全部后代锁。
+清理与加锁在同一事务内完成,旧 owner 在接管后无法通过续租恢复这些记录。
+全局增量清理每次加锁最多删除 256 条记录;冲突记录清理不受此上限限制,
+因此过期子树较大时仍会增加事务开销。
+
+不能将数据库放在 EFS、NFS 或 SMB 上。SQLite WAL 要求参与者位于同一主机,不支持网络文件系统;
+频繁更新锁记录还会增加同步 I/O。如果 `storage.workspace` 位于 EFS,默认数据库路径也会落在 EFS。
+将数据库改到各容器本地磁盘会形成独立的锁状态,无法协调多个副本。
+
+多个容器或主机共享 EFS 时,使用共享 Redis PathLock:
+设置 `storage.agfs.pathlock.provider="cache"` 和顶层 `cache.provider="redis"`。
+所有副本必须连接同一个 Redis 部署,并使用相同的顶层 `service_name` 和锁过期配置。
+参见[共享 Redis 配置示例](../guides/01-configuration.md)。
+共享 QueueFS 也需选择适合该部署的后端,例如 `storage.agfs.queuefs.backend="cache"`;
+仅修改 PathLock 不会改变默认的 SQLite 队列后端。
+
+切换 provider 前需停止全部参与进程,
+SQLite 与 filesystem 锁文件不共享协议。进程运行期间不能删除数据库及其 WAL/SHM 文件。
+崩溃进程的锁在 `lock_expire_secs`(默认 30 秒)后可被接管。
+此配置不会改变 workspace 进程锁或其他后端的并发限制。
+
远程存储后端还需要配置 endpoint、bucket/collection、鉴权和超时等字段。完整后端示例见[配置指南](../guides/01-configuration.md#storage)。
`parse_output.mode=local` 可避免把 parser 中间产物写入共享 AGFS。当前 worker
diff --git a/docs/zh/guides/01-configuration.md b/docs/zh/guides/01-configuration.md
index 926720ad5..6460ca7a1 100644
--- a/docs/zh/guides/01-configuration.md
+++ b/docs/zh/guides/01-configuration.md
@@ -1429,10 +1429,20 @@ Redis 命名空间。
| 参数 | 类型 | 说明 | 默认值 |
|------|------|------|--------|
-| `provider` | str | `filesystem`、`memory` 或 `cache`;`cache` 复用 Redis CacheRuntime | `filesystem` |
+| `provider` | str | `filesystem`、`memory`、`sqlite` 或 `cache`;`cache` 复用 Redis CacheRuntime | `filesystem` |
+| `sqlite_path` | str / null | 可显式覆盖本地共享锁数据库的绝对路径。见 [SQLite 配置](../configuration/01-server.md#storage) | 使用 `sqlite` 时为 `{storage.workspace}/_system/pathlock/pathlock.db` |
| `lock_expire_secs` | float | 未刷新的锁进入 stale 状态前的秒数;不得小于 `1.0` | `30.0` |
| `lock_timeout_secs` | float | 已废弃且忽略;运行时等待超时固定为 `0.0` | `0.0` |
+SQLite PathLock 仅适用于同一主机上的进程共享同一个本地磁盘数据库文件。
+不能将数据库放在 EFS/NFS/SMB,也不能为每个副本配置独立的容器本地数据库。
+workspace 位于 EFS 时,默认 `sqlite_path` 也会落在 EFS。
+详见 [SQLite 部署限制](../configuration/01-server.md#storage)。
+
+多个容器或主机共享 EFS 时,使用下面的共享 Redis PathLock 配置。
+所有副本必须连接同一个 Redis 部署,并使用相同的顶层 `service_name` 和锁过期配置。
+示例同时使用 Redis QueueFS,避免默认的 SQLite 队列数据库落在 EFS。
+
```json
{
"service_name": "production",
diff --git a/docs/zh/guides/14-ragfs-cache.md b/docs/zh/guides/14-ragfs-cache.md
index da3fc4851..181a6b105 100644
--- a/docs/zh/guides/14-ragfs-cache.md
+++ b/docs/zh/guides/14-ragfs-cache.md
@@ -157,7 +157,7 @@ Cache PathLock 和 cache-backed 多写 metadata 提供 Redis namespace。
| 参数 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
-| `provider` | str | `"filesystem"` | `filesystem`、`memory` 或 `cache` |
+| `provider` | str | `"filesystem"` | `filesystem`、`memory`、`sqlite` 或 `cache`;见 [SQLite 配置](../configuration/01-server.md#storage) |
| `lock_expire_secs` | float | `30.0` | 锁 stale 超时;不得小于 `1.0` |
Redis 配置:
diff --git a/openviking/storage/viking_fs/_snapshot.py b/openviking/storage/viking_fs/_snapshot.py
index 4f2c67817..bb6ef18f0 100644
--- a/openviking/storage/viking_fs/_snapshot.py
+++ b/openviking/storage/viking_fs/_snapshot.py
@@ -308,14 +308,16 @@ class _SnapshotMixin:
@staticmethod
def _snapshot_missing_target_lock_kind() -> Optional[str]:
- """Lock kind for a missing commit target: Tree on Redis, none on filesystem."""
+ """Logical-path providers can protect a missing commit target with a Tree lock."""
try:
from openviking_cli.utils.config.open_viking_config import get_openviking_config
provider = get_openviking_config().storage.agfs.pathlock.provider
except Exception:
provider = "filesystem"
- return "tree" if provider == "cache" else None
+ # TODO: query the provider's LogicalPath capability through the binding
+ # instead of extending this list for each new logical-path backend.
+ return "tree" if provider in {"cache", "sqlite"} else None
async def restore(
self,
diff --git a/openviking/utils/agfs_utils.py b/openviking/utils/agfs_utils.py
index 396e35a63..ddcc236d2 100644
--- a/openviking/utils/agfs_utils.py
+++ b/openviking/utils/agfs_utils.py
@@ -49,6 +49,22 @@ class RagfsBindingConfig:
cachefs = getattr(self.agfs, "cachefs", None)
cachefs_backend = getattr(cachefs, "backend", "local")
pathlock = self.agfs.pathlock.model_dump(mode="json", exclude_none=True)
+ if pathlock.get("provider") == "sqlite":
+ sqlite_path = pathlock.get("sqlite_path")
+ if sqlite_path is None:
+ workspace = getattr(self.agfs, "path", None)
+ if not workspace:
+ raise ValueError(
+ "agfs_config.path is required for the default SQLite lock database"
+ )
+ # Resolve at binding time so later workspace overrides are respected.
+ database = (
+ Path(workspace).expanduser().resolve() / "_system" / "pathlock" / "pathlock.db"
+ )
+ else:
+ database = Path(sqlite_path).resolve()
+ database.parent.mkdir(parents=True, exist_ok=True)
+ pathlock["sqlite_path"] = str(database)
pathlock_uses_cache = pathlock.get("provider") == "cache"
backups = getattr(self.agfs, "backups", None)
uses_runtime = (
diff --git a/openviking_cli/utils/config/agfs_config.py b/openviking_cli/utils/config/agfs_config.py
index d4698a0db..2b93632f9 100644
--- a/openviking_cli/utils/config/agfs_config.py
+++ b/openviking_cli/utils/config/agfs_config.py
@@ -3,6 +3,7 @@
from __future__ import annotations
import math
+import os
from enum import Enum
from typing import Any, List, Literal, Optional
from urllib.parse import urlparse
@@ -298,7 +299,12 @@ class AGFSPathLockConfig(BaseModel):
provider: str = Field(
default="filesystem",
- description="PathLock provider: 'filesystem' | 'memory' | 'cache'",
+ description="PathLock provider: 'filesystem' | 'memory' | 'sqlite' | 'cache'",
+ )
+ sqlite_path: Optional[str] = Field(
+ default=None,
+ description="Absolute local SQLite lock database file shared by all participating processes. "
+ "Defaults to '{storage.workspace}/_system/pathlock/pathlock.db' when not set.",
)
lock_timeout_secs: float = Field(
default=0.0,
@@ -312,8 +318,16 @@ class AGFSPathLockConfig(BaseModel):
@model_validator(mode="after")
def validate_config(self):
"""Validate provider and timeout/expiry ranges."""
- if self.provider not in {"filesystem", "memory", "cache"}:
- raise ValueError("pathlock provider must be one of: 'filesystem', 'memory', 'cache'")
+ if self.provider not in {"filesystem", "memory", "sqlite", "cache"}:
+ raise ValueError(
+ "pathlock provider must be one of: 'filesystem', 'memory', 'sqlite', 'cache'"
+ )
+ if (
+ self.provider == "sqlite"
+ and self.sqlite_path is not None
+ and not os.path.isabs(self.sqlite_path)
+ ):
+ raise ValueError("pathlock sqlite_path must be an absolute local file path")
if not math.isfinite(self.lock_expire_secs) or self.lock_expire_secs < 1.0:
raise ValueError("pathlock lock_expire_secs must be finite and >= 1.0")
return self
diff --git a/tests/misc/test_config_validation.py b/tests/misc/test_config_validation.py
index 409e2442e..e4c68af02 100644
--- a/tests/misc/test_config_validation.py
+++ b/tests/misc/test_config_validation.py
@@ -19,6 +19,7 @@ from openviking_cli.utils.config.cache_config import CacheConfig
from openviking_cli.utils.config.consts import OPENVIKING_CONFIG_ENV
from openviking_cli.utils.config.embedding_config import EmbeddingConfig, EmbeddingModelConfig
from openviking_cli.utils.config.open_viking_config import OpenVikingConfig
+from openviking_cli.utils.config.storage_config import StorageConfig
from openviking_cli.utils.config.vectordb_config import VectorDBBackendConfig, VolcengineConfig
from openviking_cli.utils.config.vlm_config import VLMConfig
@@ -866,6 +867,74 @@ def test_redis_pathlock_enables_shared_runtime_without_cachefs(tmp_path):
assert binding["service_name"] == "prod-a"
+def test_sqlite_pathlock_binding_without_redis(tmp_path):
+ database = str(tmp_path / "custom" / "locks.sqlite3")
+ config = AGFSConfig(
+ path=str(tmp_path), pathlock={"provider": "sqlite", "sqlite_path": database}
+ )
+ binding = RagfsBindingConfig(agfs=config, service_name="local-a").to_binding_dict()
+ assert binding["pathlock"]["sqlite_path"] == database
+ assert binding["pathlock"]["provider"] == "sqlite"
+ assert binding["cache"]["runtime_enabled"] is False
+ assert Path(database).parent.is_dir()
+ for path in ["", "relative.sqlite3", ":memory:"]:
+ with pytest.raises(ValueError, match="sqlite_path"):
+ AGFSConfig(path=str(tmp_path), pathlock={"provider": "sqlite", "sqlite_path": path})
+
+
[email protected]("sqlite_path", [{}, {"sqlite_path": None}])
+def test_sqlite_pathlock_default_uses_final_workspace(tmp_path, monkeypatch, sqlite_path):
+ initial = tmp_path / "initial"
+ storage = StorageConfig(
+ workspace=str(initial),
+ agfs={"pathlock": {"provider": "sqlite", **sqlite_path}},
+ )
+ assert storage.agfs.pathlock.sqlite_path is None
+ assert not (initial / "_system" / "pathlock").exists()
+
+ # Runtime workspace overrides happen after model validation.
+ final = tmp_path / "final"
+ storage.workspace = str(final)
+ storage.agfs.path = str(final)
+ binding_config = RagfsBindingConfig(agfs=storage.agfs, service_name="local-a")
+ expected = final / "_system" / "pathlock" / "pathlock.db"
+ first = binding_config.to_binding_dict()
+ assert first["pathlock"]["sqlite_path"] == str(expected)
+ assert expected.parent.is_dir()
+ assert not (initial / "_system" / "pathlock").exists()
+ assert storage.agfs.pathlock.sqlite_path is None
+ assert first["cache"]["runtime_enabled"] is False
+
+ # Another process with a different cwd resolves the same absolute workspace.
+ monkeypatch.chdir(initial)
+ second = RagfsBindingConfig(agfs=storage.agfs, service_name="local-a").to_binding_dict()
+ assert second["pathlock"]["sqlite_path"] == first["pathlock"]["sqlite_path"]
+
+
+def test_sqlite_pathlock_explicit_path_survives_workspace_override(tmp_path):
+ database = tmp_path / "custom" / "locks.db"
+ config = AGFSConfig(
+ path=str(tmp_path / "initial"),
+ pathlock={"provider": "sqlite", "sqlite_path": str(database)},
+ )
+ config.path = str(tmp_path / "final")
+ binding = RagfsBindingConfig(agfs=config).to_binding_dict()
+ assert binding["pathlock"]["sqlite_path"] == str(database)
+ assert database.parent.is_dir()
+ assert not (tmp_path / "final" / "_system" / "pathlock").exists()
+
+
+def test_sqlite_pathlock_default_requires_workspace_and_leaves_other_providers_alone(tmp_path):
+ config = AGFSConfig(pathlock={"provider": "sqlite"})
+ with pytest.raises(ValueError, match="agfs_config.path"):
+ RagfsBindingConfig(agfs=config).to_binding_dict()
+ workspace = tmp_path / "unused"
+ config = AGFSConfig(path=str(workspace))
+ binding = RagfsBindingConfig(agfs=config).to_binding_dict()
+ assert "sqlite_path" not in binding["pathlock"]
+ assert not workspace.exists()
+
+
def test_create_agfs_client_uses_single_binding_config_object(monkeypatch, tmp_path):
agfs_config = AGFSConfig(
path=str(tmp_path),
diff --git a/tests/unit/test_snapshot_rebuild_context.py b/tests/unit/test_snapshot_rebuild_context.py
index cf57e5d72..33f4deb25 100644
--- a/tests/unit/test_snapshot_rebuild_context.py
+++ b/tests/unit/test_snapshot_rebuild_context.py
@@ -12,6 +12,19 @@ from openviking.storage.viking_fs import VikingFS
from openviking_cli.session.user_id import UserIdentifier
+ ("provider", "expected"),
+ [("sqlite", "tree"), ("cache", "tree"), ("filesystem", None), ("memory", None)],
+)
+def test_missing_snapshot_target_uses_logical_provider_tree_lock(monkeypatch, provider, expected):
+ config = Mock()
+ config.storage.agfs.pathlock.provider = provider
+ monkeypatch.setattr(
+ "openviking_cli.utils.config.open_viking_config.get_openviking_config", lambda: config
+ )
+ assert VikingFS._snapshot_missing_target_lock_kind() == expected
+
+
@pytest.mark.asyncio
async def test_fallback_rebuild_detaches_all_operations(monkeypatch):
ctx = RequestContext(user=UserIdentifier("account", "user"), role=Role.ROOT)