Skip to content

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

refactor(pathlock):using rust implement instead python (#3602)

baojun-zhang2f9451231e8b
diff --git a/Cargo.lock b/Cargo.lock
index 8be5cb555..5f45a69ec 100644
--- a/Cargo.lock
+++ b/Cargo.lock
@@ -1849,6 +1849,16 @@ dependencies = [
"subtle",
]
+[[package]]
+name = "filelocks"
+version = "0.1.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "54c1e4f9fd884a066beb8cc4677dea1188d2f2eaf70518f3a37e46551cfe3431"
+dependencies = [
+ "libc",
+ "windows-sys 0.61.2",
+]
+
[[package]]
name = "find-msvc-tools"
version = "0.1.9"
@@ -3880,6 +3890,7 @@ dependencies = [
"chrono",
"criterion",
"dashmap",
+ "filelocks",
"flate2",
"futures",
"gix-actor",
@@ -3903,6 +3914,7 @@ dependencies = [
"rusqlite",
"serde",
"serde_json",
+ "sha1",
"sha2",
"sqlx",
"tempfile",
diff --git a/crates/ragfs-python/src/lib.rs b/crates/ragfs-python/src/lib.rs
index d10db441c..042fec626 100644
--- a/crates/ragfs-python/src/lib.rs
+++ b/crates/ragfs-python/src/lib.rs
@@ -8,10 +8,61 @@ use pyo3::exceptions::{PyRuntimeError, PyValueError};
use pyo3::prelude::*;
use pyo3::types::{PyBytes, PyDict, PyList, PyType};
use std::collections::HashMap;
+use std::sync::OnceLock;
+
+/// Cached reference to the Python `openviking.storage.errors.LockAcquisitionError` class,
+/// imported at module init so that native and Python code share the same exception type.
+static LOCK_ACQUISITION_ERROR_TYPE: OnceLock<Py<PyType>> = OnceLock::new();
+
+/// Map a PathLockError to the appropriate Python exception.
+fn pathlock_err_to_py(err: PathLockError) -> PyErr {
+ match &err {
+ PathLockError::Conflict { .. }
+ | PathLockError::Timeout { .. }
+ | PathLockError::HandoffFailed(_) => {
+ #[allow(deprecated)]
+ Python::with_gil(|py| {
+ let ty = LOCK_ACQUISITION_ERROR_TYPE
+ .get()
+ .expect("LockAcquisitionError not initialized");
+ PyErr::from_type(ty.bind(py).clone(), err.to_string())
+ })
+ }
+ PathLockError::InvalidRequest(_) => PyValueError::new_err(err.to_string()),
+ _ => PyRuntimeError::new_err(err.to_string()),
+ }
+}
use std::fs;
use std::future::Future;
use std::sync::Arc;
-use std::time::UNIX_EPOCH;
+use std::time::{Duration, UNIX_EPOCH};
+
+/// Validate and convert a wait timeout from Python.
+///
+/// Must be finite and non-negative. Returns `Duration::from_secs_f64(v)`.
+/// NaN, negative, or infinite → `ValueError`.
+fn validate_timeout_secs(v: f64) -> PyResult<Duration> {
+ if v.is_finite() && v >= 0.0 {
+ Ok(Duration::from_secs_f64(v))
+ } else {
+ Err(PyValueError::new_err(
+ "timeout_secs must be a finite non-negative number",
+ ))
+ }
+}
+
+/// Validate and convert a lock expire duration from Python config.
+///
+/// Must be finite, positive, and at least 1.0 second.
+fn validate_expire_secs(v: f64) -> PyResult<f64> {
+ if v.is_finite() && v >= 1.0 {
+ Ok(v)
+ } else {
+ Err(PyValueError::new_err(
+ "lock_expire_secs must be a finite number >= 1.0",
+ ))
+ }
+}
use ragfs::cache::{
CacheError, CacheNamespace, CachePolicy, CacheProvider, CacheResult, CacheTraversalMode,
@@ -19,10 +70,48 @@ use ragfs::cache::{
};
use ragfs::core::builder::EncryptionConfig;
use ragfs::core::{
- build_default_stack, register_builtin_plugins, ConfigValue, FileInfo, FileSystem,
+ build_default_stack, build_stack_with_mountable, ConfigValue, FileInfo, FileSystem,
FilesystemStats, FsContext, FsContextInner, FsOperation, GlobPage, GrepResult, MountableFS,
- OperationStats, PluginConfig, RagfsConfig, StatsWrappedFS, TreeEntry, WriteFlag, FS_CTX,
+ OperationStats, PathLockContext, PluginConfig, RagfsConfig, TreeEntry, WriteFlag, FS_CTX,
};
+use ragfs::lock::{
+ BorrowedPathLockLease, OwnedPathLockLease, PathLockConfig, PathLockHandoffRef, PathLockKind,
+ PathLockManager, PathLockRequest,
+};
+use ragfs::lock::types::PathLockError;
+
+/// Parse one Python pathlock request without silently defaulting invalid fields.
+fn parse_pathlock_request(raw: &HashMap<String, String>) -> PyResult<PathLockRequest> {
+ let path = raw
+ .get("path")
+ .filter(|path| !path.is_empty() && path.starts_with('/'))
+ .ok_or_else(|| PyValueError::new_err("pathlock request.path must be an absolute path"))?;
+ let kind = match raw.get("kind").map(String::as_str) {
+ Some("exact") => PathLockKind::Exact,
+ Some("tree") => PathLockKind::Tree,
+ _ => {
+ return Err(PyValueError::new_err(
+ "pathlock request.kind must be 'exact' or 'tree'",
+ ));
+ }
+ };
+ Ok(PathLockRequest {
+ path: path.clone(),
+ kind,
+ })
+}
+
+/// Parse a non-empty Python pathlock request batch.
+fn parse_pathlock_request_batch(
+ requests: &[HashMap<String, String>],
+) -> PyResult<Vec<PathLockRequest>> {
+ if requests.is_empty() {
+ return Err(PyValueError::new_err(
+ "pathlock request batch must not be empty",
+ ));
+ }
+ requests.iter().map(parse_pathlock_request).collect()
+}
#[derive(Debug, Clone, PartialEq, Eq)]
enum CacheProviderKind {
@@ -800,11 +889,135 @@ fn py_to_json_value(v: &Bound<'_, PyAny>) -> PyResult<serde_json::Value> {
/// "every ragfs call carries a ctx" invariant holds. Missing `account_id` is represented as an
/// empty field; `FsContextView::account_id()` treats it as absent, so encrypted content operations
/// fail fast instead of using an accidental empty tenant key.
+///
+/// When the dict contains `"disable_auto_pathlock": "true"`, the `PathLockWrappedFS` auto-lock
+/// layer is suppressed so callers that already hold a pathlock lease can safely delegate to the
+/// inner filesystem without double-locking.
fn build_fs_context(ctx: Option<HashMap<String, String>>) -> FsContext {
- let account_id = ctx
- .and_then(|m| m.get("account_id").cloned())
- .unwrap_or_default();
- Arc::new(FsContextInner::new(account_id))
+ let mut account_id = String::new();
+ let mut disable_auto_pathlock = false;
+ let mut lease_ref: Option<String> = None;
+ if let Some(m) = &ctx {
+ account_id = m.get("account_id").cloned().unwrap_or_default();
+ disable_auto_pathlock = m.get("disable_auto_pathlock").map(|s| s == "true").unwrap_or(false);
+ lease_ref = m.get("lease_ref").cloned();
+ }
+ let pathlock = if disable_auto_pathlock || lease_ref.is_some() {
+ Some(PathLockContext {
+ lease_ref,
+ disable_auto_pathlock,
+ })
+ } else {
+ None
+ };
+ Arc::new(FsContextInner::with_pathlock(account_id, pathlock.unwrap_or_default()))
+}
+
+/// Convert an OwnedPathLockLease to a Python dict.
+fn owned_lease_to_py_dict(py: Python<'_>, lease: &OwnedPathLockLease) -> PyResult<Py<PyAny>> {
+ let dict = PyDict::new(py);
+ dict.set_item("lease_ref", &lease.lease.lease_ref)?;
+ dict.set_item("owner_id", &lease.lease.owner_id)?;
+ dict.set_item("lock_paths", &lease.lease.lock_paths)?;
+ dict.set_item("ownership_ref", &lease.ownership_ref)?;
+ dict.set_item("owned", true)?;
+ Ok(dict.into())
+}
+
+/// Convert a BorrowedPathLockLease to a Python dict.
+fn borrowed_lease_to_py_dict(py: Python<'_>, lease: &BorrowedPathLockLease) -> PyResult<Py<PyAny>> {
+ let dict = PyDict::new(py);
+ dict.set_item("lease_ref", &lease.lease.lease_ref)?;
+ dict.set_item("owner_id", &lease.lease.owner_id)?;
+ dict.set_item("lock_paths", &lease.lease.lock_paths)?;
+ dict.set_item("owned", false)?;
+ Ok(dict.into())
+}
+
+/// Require an owned marker and return its opaque lease and lifecycle capability refs.
+fn require_owned_lease_ref(
+ py: Python<'_>,
+ ref_dict: &HashMap<String, Py<PyAny>>,
+) -> PyResult<(String, String)> {
+ let owned: bool = ref_dict
+ .get("owned")
+ .map(|v| v.extract(py))
+ .transpose()?
+ .unwrap_or(false);
+ if !owned {
+ return Err(PyValueError::new_err(
+ "lease ref is not owned; release/refresh/handoff require an owned lease",
+ ));
+ }
+ let lease_ref: String = ref_dict
+ .get("lease_ref")
+ .ok_or_else(|| PyValueError::new_err("owned_lease_ref.lease_ref required"))?
+ .extract(py)?;
+ let ownership_ref: String = ref_dict
+ .get("ownership_ref")
+ .ok_or_else(|| PyValueError::new_err("owned_lease_ref.ownership_ref required"))?
+ .extract(py)?;
+ if lease_ref.is_empty() || ownership_ref.is_empty() {
+ return Err(PyValueError::new_err(
+ "owned lease and ownership refs must not be empty",
+ ));
+ }
+ Ok((lease_ref, ownership_ref))
+}
+
+/// Extract an opaque PathLock lease ref without granting lifecycle permissions.
+fn extract_lease_ref(py: Python<'_>, lease_ref: &Py<PyAny>) -> PyResult<String> {
+ if let Ok(raw) = lease_ref.extract::<String>(py) {
+ if !raw.is_empty() {
+ return Ok(raw);
+ }
+ }
+ let ref_dict: HashMap<String, Py<PyAny>> = lease_ref.extract(py)?;
+ ref_dict
+ .get("lease_ref")
+ .ok_or_else(|| PyValueError::new_err("lease_ref.lease_ref required"))?
+ .extract(py)
+}
+
+/// Extract an owned PathLock lease and lifecycle capability from a typed dictionary.
+fn extract_owned_lease_ref(
+ py: Python<'_>,
+ lease_ref: &Py<PyAny>,
+) -> PyResult<(String, String)> {
+ let ref_dict: HashMap<String, Py<PyAny>> = lease_ref.extract(py)?;
+ require_owned_lease_ref(py, &ref_dict)
+}
+
+/// Extract an optional owned lease capability used for reentrant acquisition.
+fn extract_optional_owned_lease_ref(
+ py: Python<'_>,
+ lease_ref: Option<&Py<PyAny>>,
+) -> PyResult<Option<(String, String)>> {
+ lease_ref
+ .map(|value| extract_owned_lease_ref(py, value))
+ .transpose()
+}
+
+/// Convert a PathLockHandoffRef to a Python dict.
+fn handoff_ref_to_py_dict(py: Python<'_>, handoff: &PathLockHandoffRef) -> PyResult<Py<PyAny>> {
+ let dict = PyDict::new(py);
+ dict.set_item("owner_id", &handoff.owner_id)?;
+ dict.set_item("lock_paths", &handoff.lock_paths)?;
+ let covered = PyList::empty(py);
+ for req in &handoff.covered_paths {
+ let item = PyDict::new(py);
+ item.set_item("path", &req.path)?;
+ item.set_item(
+ "kind",
+ match req.kind {
+ PathLockKind::Exact => "exact",
+ PathLockKind::Tree => "tree",
+ },
+ )?;
+ covered.append(item)?;
+ }
+ dict.set_item("covered_paths", covered)?;
+ Ok(dict.into())
}
#[derive(serde::Deserialize)]
@@ -854,6 +1067,8 @@ struct RAGFSBindingClient {
rt: tokio::runtime::Runtime,
git_service: Option<Arc<ragfs::git::GitService>>,
git_backend: Option<String>,
+ /// PathLock manager. OpenViking always builds ragfs with PathLock enabled.
+ pathlock_manager: Arc<PathLockManager>,
}
impl RAGFSBindingClient {
@@ -872,6 +1087,11 @@ impl RAGFSBindingClient {
.block_on(FS_CTX.scope(ctx, async move { f().await }))
})
}
+
+ /// Clone the PathLock manager shared by this binding client.
+ fn clone_pathlock_manager(&self) -> Arc<PathLockManager> {
+ self.pathlock_manager.clone()
+ }
}
#[pymethods]
@@ -931,6 +1151,28 @@ impl RAGFSBindingClient {
.map_err(|e| PyRuntimeError::new_err(format!("Invalid git config: {e}")))?;
inline_git_cfg = Some(git_cfg);
}
+ if let Some(pl_obj) = cfg.get("pathlock") {
+ let pl_value = py_to_json_value(pl_obj.bind(py))?;
+ let provider = pl_value
+ .get("provider")
+ .and_then(|v| v.as_str())
+ .unwrap_or("filesystem");
+ if !matches!(provider, "filesystem" | "memory") {
+ return Err(PyValueError::new_err(
+ "pathlock.provider must be 'filesystem' or 'memory'",
+ ));
+ }
+ let lock_expire_secs = validate_expire_secs(
+ pl_value
+ .get("lock_expire_secs")
+ .and_then(|v| v.as_f64())
+ .unwrap_or(300.0),
+ )?;
+ ragfs_cfg.pathlock = PathLockConfig {
+ provider: provider.to_string(),
+ lock_expire_secs,
+ };
+ }
}
let cache_config = match runtime_cache_config {
@@ -957,18 +1199,7 @@ impl RAGFSBindingClient {
CacheNamespace::new(&cache_config.namespace),
cache_policy_from_config(&cache_config),
));
- rt.block_on(async {
- register_builtin_plugins(&mountable).await;
- if let Some(enc) = &ragfs_cfg.encryption {
- mountable
- .set_encryption_config(Some(enc.root_key), Some(enc.provider_type))
- .await;
- }
- });
- let top: Arc<dyn FileSystem> = Arc::new(StatsWrappedFS::with_arc(
- mountable.clone() as Arc<dyn FileSystem>
- ));
- ragfs::core::RagfsStack { mountable, top }
+ rt.block_on(build_stack_with_mountable(ragfs_cfg, mountable))
} else {
rt.block_on(build_default_stack(ragfs_cfg))
};
@@ -989,6 +1220,7 @@ impl RAGFSBindingClient {
rt,
git_service,
git_backend,
+ pathlock_manager: stack.pathlock_manager,
})
}
@@ -1783,6 +2015,491 @@ impl RAGFSBindingClient {
))
}
+ // ── PathLock API ──
+
+ /// Acquire an exact lock on a single path.
+ #[pyo3(signature = (ctx, path, timeout_secs=0.0, owner_lease_ref=None))]
+ fn pathlock_acquire_exact(
+ &self,
+ py: Python<'_>,
+ ctx: Option<HashMap<String, String>>,
+ path: String,
+ timeout_secs: f64,
+ owner_lease_ref: Option<Py<PyAny>>,
+ ) -> PyResult<Py<PyAny>> {
+ let mgr = self.clone_pathlock_manager();
+ let fs_ctx = build_fs_context(ctx);
+ let timeout = validate_timeout_secs(timeout_secs)?;
+ let owner_capability =
+ extract_optional_owned_lease_ref(py, owner_lease_ref.as_ref())?;
+ let lease = self.run_scoped(py, fs_ctx, move || {
+ let mgr = mgr.clone();
+ let path = path.clone();
+ let capability = owner_capability.clone();
+ async move {
+ let capability = capability
+ .as_ref()
+ .map(|(lease_ref, ownership_ref)| {
+ (lease_ref.as_str(), ownership_ref.as_str())
+ });
+ mgr.acquire_exact(&path, timeout, capability).await
+ }
+ })
+ .map_err(pathlock_err_to_py)?;
+ Python::attach(|py| owned_lease_to_py_dict(py, &lease))
+ }
+
+ /// Acquire exact locks on multiple paths.
+ #[pyo3(signature = (ctx, paths, timeout_secs=0.0, owner_lease_ref=None))]
+ fn pathlock_acquire_exact_batch(
+ &self,
+ py: Python<'_>,
+ ctx: Option<HashMap<String, String>>,
+ paths: Vec<String>,
+ timeout_secs: f64,
+ owner_lease_ref: Option<Py<PyAny>>,
+ ) -> PyResult<Py<PyAny>> {
+ let mgr = self.clone_pathlock_manager();
+ let fs_ctx = build_fs_context(ctx);
+ let timeout = validate_timeout_secs(timeout_secs)?;
+ let owner_capability =
+ extract_optional_owned_lease_ref(py, owner_lease_ref.as_ref())?;
+ let lease = self.run_scoped(py, fs_ctx, move || {
+ let mgr = mgr.clone();
+ let paths = paths.clone();
+ let capability = owner_capability.clone();
+ async move {
+ let capability = capability
+ .as_ref()
+ .map(|(lease_ref, ownership_ref)| {
+ (lease_ref.as_str(), ownership_ref.as_str())
+ });
+ mgr.acquire_exact_batch(&paths, timeout, capability).await
+ }
+ })
+ .map_err(pathlock_err_to_py)?;
+ Python::attach(|py| owned_lease_to_py_dict(py, &lease))
+ }
+
+ /// Acquire a tree lock on a single path.
+ #[pyo3(signature = (ctx, path, timeout_secs=0.0, owner_lease_ref=None))]
+ fn pathlock_acquire_tree(
+ &self,
+ py: Python<'_>,
+ ctx: Option<HashMap<String, String>>,
+ path: String,
+ timeout_secs: f64,
+ owner_lease_ref: Option<Py<PyAny>>,
+ ) -> PyResult<Py<PyAny>> {
+ let mgr = self.clone_pathlock_manager();
+ let fs_ctx = build_fs_context(ctx);
+ let timeout = validate_timeout_secs(timeout_secs)?;
+ let owner_capability =
+ extract_optional_owned_lease_ref(py, owner_lease_ref.as_ref())?;
+ let lease = self.run_scoped(py, fs_ctx, move || {
+ let mgr = mgr.clone();
+ let path = path.clone();
+ let capability = owner_capability.clone();
+ async move {
+ let capability = capability
+ .as_ref()
+ .map(|(lease_ref, ownership_ref)| {
+ (lease_ref.as_str(), ownership_ref.as_str())
+ });
+ mgr.acquire_tree(&path, timeout, capability).await
+ }
+ })
+ .map_err(pathlock_err_to_py)?;
+ Python::attach(|py| owned_lease_to_py_dict(py, &lease))
+ }
+
+ /// Acquire tree locks on multiple paths.
+ #[pyo3(signature = (ctx, paths, timeout_secs=0.0, owner_lease_ref=None))]
+ fn pathlock_acquire_tree_batch(
+ &self,
+ py: Python<'_>,
+ ctx: Option<HashMap<String, String>>,
+ paths: Vec<String>,
+ timeout_secs: f64,
+ owner_lease_ref: Option<Py<PyAny>>,
+ ) -> PyResult<Py<PyAny>> {
+ let mgr = self.clone_pathlock_manager();
+ let fs_ctx = build_fs_context(ctx);
+ let timeout = validate_timeout_secs(timeout_secs)?;
+ let owner_capability =
+ extract_optional_owned_lease_ref(py, owner_lease_ref.as_ref())?;
+ let lease = self.run_scoped(py, fs_ctx, move || {
+ let mgr = mgr.clone();
+ let paths = paths.clone();
+ let capability = owner_capability.clone();
+ async move {
+ let capability = capability
+ .as_ref()
+ .map(|(lease_ref, ownership_ref)| {
+ (lease_ref.as_str(), ownership_ref.as_str())
+ });
+ mgr.acquire_tree_batch(&paths, timeout, capability).await
+ }
+ })
+ .map_err(pathlock_err_to_py)?;
+ Python::attach(|py| owned_lease_to_py_dict(py, &lease))
+ }
+
+ /// Acquire a mixed batch of exact and tree locks.
+ #[pyo3(signature = (ctx, exact_paths, tree_paths, timeout_secs=0.0, owner_lease_ref=None))]
+ fn pathlock_acquire_exact_tree_batch(
+ &self,
+ py: Python<'_>,
+ ctx: Option<HashMap<String, String>>,
+ exact_paths: Vec<String>,
+ tree_paths: Vec<String>,
+ timeout_secs: f64,
+ owner_lease_ref: Option<Py<PyAny>>,
+ ) -> PyResult<Py<PyAny>> {
+ let mgr = self.clone_pathlock_manager();
+ let fs_ctx = build_fs_context(ctx);
+ let timeout = validate_timeout_secs(timeout_secs)?;
+ let owner_capability =
+ extract_optional_owned_lease_ref(py, owner_lease_ref.as_ref())?;
+ let lease = self.run_scoped(py, fs_ctx, move || {
+ let mgr = mgr.clone();
+ let exact = exact_paths.clone();
+ let tree = tree_paths.clone();
+ let capability = owner_capability.clone();
+ async move {
+ let capability = capability
+ .as_ref()
+ .map(|(lease_ref, ownership_ref)| {
+ (lease_ref.as_str(), ownership_ref.as_str())
+ });
+ mgr.acquire_exact_tree_batch(&exact, &tree, timeout, capability)
+ .await
+ }
+ })
+ .map_err(pathlock_err_to_py)?;
+ Python::attach(|py| owned_lease_to_py_dict(py, &lease))
+ }
+
+ /// Acquire a batch of locks from a list of request dicts.
+ /// Each request dict: {"path": str, "kind": "exact"|"tree"}
+ #[pyo3(signature = (ctx, requests, timeout_secs=0.0, owner_lease_ref=None))]
+ fn pathlock_acquire_batch(
+ &self,
+ py: Python<'_>,
+ ctx: Option<HashMap<String, String>>,
+ requests: Vec<HashMap<String, String>>,
+ timeout_secs: f64,
+ owner_lease_ref: Option<Py<PyAny>>,
+ ) -> PyResult<Py<PyAny>> {
+ let mgr = self.clone_pathlock_manager();
+ let fs_ctx = build_fs_context(ctx);
+ let timeout = validate_timeout_secs(timeout_secs)?;
+ let owner_capability =
+ extract_optional_owned_lease_ref(py, owner_lease_ref.as_ref())?;
+
+ let lock_requests = parse_pathlock_request_batch(&requests)?;
+
+ let lease = self.run_scoped(py, fs_ctx, move || {
+ let mgr = mgr.clone();
+ let reqs = lock_requests.clone();
+ let capability = owner_capability.clone();
+ async move {
+ let capability = capability
+ .as_ref()
+ .map(|(lease_ref, ownership_ref)| {
+ (lease_ref.as_str(), ownership_ref.as_str())
+ });
+ mgr.acquire_batch(&reqs, timeout, capability).await
+ }
+ })
+ .map_err(pathlock_err_to_py)?;
+ Python::attach(|py| owned_lease_to_py_dict(py, &lease))
+ }
+
+ /// Create a borrowed view of an owned lease.
+ #[pyo3(signature = (ctx, owned_lease_ref))]
+ fn pathlock_as_borrowed(
+ &self,
+ py: Python<'_>,
+ ctx: Option<HashMap<String, String>>,
+ owned_lease_ref: Py<PyAny>,
+ ) -> PyResult<Py<PyAny>> {
+ let mgr = self.clone_pathlock_manager();
+ let mgr2 = mgr.clone();
+ let fs_ctx = build_fs_context(ctx);
+ let lease_ref = extract_lease_ref(py, &owned_lease_ref)?;
+ let lease = self.run_scoped(py, fs_ctx, move || {
+ let mgr = mgr2.clone();
+ let lr = lease_ref.clone();
+ async move {
+ mgr.get_owned_lease_by_ref(&lr).await.ok_or_else(|| {
+ PathLockError::Internal(format!("lease not found for ref '{lr}'"))
+ })
+ }
+ })
+ .map_err(|e: PathLockError| PyRuntimeError::new_err(e.to_string()))?;
+ let borrowed = mgr.as_borrowed(&lease);
+ Python::attach(|py| borrowed_lease_to_py_dict(py, &borrowed))
+ }
+
+ /// Refresh an owned lease. Returns "refreshed", "lost", or "failed".
+ #[pyo3(signature = (ctx, owned_lease_ref))]
+ fn pathlock_refresh(
+ &self,
+ py: Python<'_>,
+ ctx: Option<HashMap<String, String>>,
+ owned_lease_ref: Py<PyAny>,
+ ) -> PyResult<String> {
+ let mgr = self.clone_pathlock_manager();
+ let fs_ctx = build_fs_context(ctx);
+ let (lease_ref, ownership_ref) = extract_owned_lease_ref(py, &owned_lease_ref)?;
+ let status = self.run_scoped(py, fs_ctx, move || {
+ let mgr = mgr.clone();
+ let lr = lease_ref.clone();
+ let ownership = ownership_ref.clone();
+ async move {
+ let lease = mgr
+ .get_owned_lease_by_capability(&lr, &ownership)
+ .await
+ .ok_or_else(|| {
+ PathLockError::InvalidRequest(format!(
+ "owned lease capability does not match ref '{lr}'"
+ ))
+ })?;
+ mgr.refresh(&lease).await
+ }
+ })
+ .map_err(pathlock_err_to_py)?;
+ Ok(status)
+ }
+
+ /// Release an owned lease.
+ #[pyo3(signature = (ctx, owned_lease_ref))]
+ fn pathlock_release(
+ &self,
+ py: Python<'_>,
+ ctx: Option<HashMap<String, String>>,
+ owned_lease_ref: Py<PyAny>,
+ ) -> PyResult<()> {
+ let mgr = self.clone_pathlock_manager();
+ let fs_ctx = build_fs_context(ctx);
+ let (lease_ref, ownership_ref) = extract_owned_lease_ref(py, &owned_lease_ref)?;
+ self.run_scoped(py, fs_ctx, move || {
+ let mgr = mgr.clone();
+ let lr = lease_ref.clone();
+ let ownership = ownership_ref.clone();
+ async move {
+ let lease = mgr
+ .get_owned_lease_by_capability(&lr, &ownership)
+ .await
+ .ok_or_else(|| {
+ PathLockError::InvalidRequest(format!(
+ "owned lease capability does not match ref '{lr}'"
+ ))
+ })?;
+ mgr.release(&lease).await
+ }
+ })
+ .map_err(pathlock_err_to_py)?;
+ Ok(())
+ }
+
+ /// Release selected lock paths from an owned lease.
+ #[pyo3(signature = (ctx, owned_lease_ref, lock_paths))]
+ fn pathlock_release_selected(
+ &self,
+ py: Python<'_>,
+ ctx: Option<HashMap<String, String>>,
+ owned_lease_ref: Py<PyAny>,
+ lock_paths: Vec<String>,
+ ) -> PyResult<()> {
+ let mgr = self.clone_pathlock_manager();
+ let fs_ctx = build_fs_context(ctx);
+ let (lease_ref, ownership_ref) = extract_owned_lease_ref(py, &owned_lease_ref)?;
+ self.run_scoped(py, fs_ctx, move || {
+ let mgr = mgr.clone();
+ let lr = lease_ref.clone();
+ let ownership = ownership_ref.clone();
+ let paths = lock_paths.clone();
+ async move {
+ let lease = mgr
+ .get_owned_lease_by_capability(&lr, &ownership)
+ .await
+ .ok_or_else(|| {
+ PathLockError::InvalidRequest(format!(
+ "owned lease capability does not match ref '{lr}'"
+ ))
+ })?;
+ mgr.release_selected(&lease, &paths).await
+ }
+ })
+ .map_err(pathlock_err_to_py)?;
+ Ok(())
+ }
+
+ /// Export a handoff ref from an owned lease.
+ #[pyo3(signature = (ctx, owned_lease_ref))]
+ fn pathlock_to_handoff(
+ &self,
+ py: Python<'_>,
+ ctx: Option<HashMap<String, String>>,
+ owned_lease_ref: Py<PyAny>,
+ ) -> PyResult<Py<PyAny>> {
+ let mgr = self.clone_pathlock_manager();
+ let fs_ctx = build_fs_context(ctx);
+ let (lease_ref, ownership_ref) = extract_owned_lease_ref(py, &owned_lease_ref)?;
+ let handoff = self.run_scoped(py, fs_ctx, move || {
+ let mgr = mgr.clone();
+ let lr = lease_ref.clone();
+ let ownership = ownership_ref.clone();
+ async move {
+ let lease = mgr
+ .get_owned_lease_by_capability(&lr, &ownership)
+ .await
+ .ok_or_else(|| {
+ PathLockError::InvalidRequest(format!(
+ "owned lease capability does not match ref '{lr}'"
+ ))
+ })?;
+ Ok(mgr.to_handoff(&lease))
+ }
+ })
+ .map_err(pathlock_err_to_py)?;
+ Python::attach(|py| handoff_ref_to_py_dict(py, &handoff))
+ }
+
+ /// Mark an owned lease as handed off.
+ #[pyo3(signature = (ctx, owned_lease_ref))]
+ fn pathlock_handoff(
+ &self,
+ py: Python<'_>,
+ ctx: Option<HashMap<String, String>>,
+ owned_lease_ref: Py<PyAny>,
+ ) -> PyResult<()> {
+ let mgr = self.clone_pathlock_manager();
+ let fs_ctx = build_fs_context(ctx);
+ let (lease_ref, ownership_ref) = extract_owned_lease_ref(py, &owned_lease_ref)?;
+ self.run_scoped(py, fs_ctx, move || {
+ let mgr = mgr.clone();
+ let lr = lease_ref.clone();
+ let ownership = ownership_ref.clone();
+ async move {
+ let lease = mgr
+ .get_owned_lease_by_capability(&lr, &ownership)
+ .await
+ .ok_or_else(|| {
+ PathLockError::InvalidRequest(format!(
+ "owned lease capability does not match ref '{lr}'"
+ ))
+ })?;
+ mgr.handoff(&lease).await
+ }
+ })
+ .map_err(pathlock_err_to_py)?;
+ Ok(())
+ }
+
+ /// Adopt a handoff ref, returning a new owned lease.
+ #[pyo3(signature = (ctx, handoff_ref))]
+ fn pathlock_adopt(
+ &self,
+ py: Python<'_>,
+ ctx: Option<HashMap<String, String>>,
+ handoff_ref: HashMap<String, Py<PyAny>>,
+ ) -> PyResult<Py<PyAny>> {
+ let mgr = self.clone_pathlock_manager();
+ let fs_ctx = build_fs_context(ctx);
+ let owner_id: String = handoff_ref
+ .get("owner_id")
+ .or_else(|| handoff_ref.get("handle_id"))
+ .ok_or_else(|| {
+ PyValueError::new_err("handoff_ref.owner_id or handoff_ref.handle_id required")
+ })?
+ .extract(py)?;
+ let lock_paths: Vec<String> = handoff_ref
+ .get("lock_paths")
+ .ok_or_else(|| PyValueError::new_err("handoff_ref.lock_paths required"))?
+ .extract(py)?;
+ if owner_id.is_empty()
+ || lock_paths.is_empty()
+ || lock_paths.iter().any(|path| !path.starts_with('/'))
+ {
+ return Err(PyValueError::new_err(
+ "handoff_ref owner_id/handle_id and absolute lock_paths are required",
+ ));
+ }
+ let covered_paths: Vec<PathLockRequest> = handoff_ref
+ .get("covered_paths")
+ .map(|v| {
+ let raw: Vec<HashMap<String, String>> = v.extract(py)?;
+ raw.iter().map(parse_pathlock_request).collect()
+ })
+ .transpose()?
+ .unwrap_or_default();
+ let handoff = PathLockHandoffRef {
+ owner_id,
+ lock_paths,
+ covered_paths,
+ };
+ let lease = self.run_scoped(py, fs_ctx, move || {
+ let mgr = mgr.clone();
+ let h = handoff.clone();
+ async move { mgr.adopt(&h).await }
+ })
+ .map_err(pathlock_err_to_py)?;
+ Python::attach(|py| owned_lease_to_py_dict(py, &lease))
+ }
+
+ /// Check if a path is locked.
+ #[pyo3(signature = (ctx, path, ignore_stale=true))]
+ fn pathlock_is_locked(
+ &self,
+ py: Python<'_>,
+ ctx: Option<HashMap<String, String>>,
+ path: String,
+ ignore_stale: bool,
+ ) -> PyResult<bool> {
+ let mgr = self.clone_pathlock_manager();
+ let fs_ctx = build_fs_context(ctx);
+ self.run_scoped(py, fs_ctx, move || {
+ let mgr = mgr.clone();
+ let p = path.clone();
+ async move { mgr.is_locked(&p, ignore_stale).await }
+ })
+ .map_err(|e| PyRuntimeError::new_err(e.to_string()))
+ }
+
+ /// Return an observability snapshot of current lock state.
+ #[pyo3(signature = (ctx=None))]
+ fn pathlock_observe(
+ &self,
+ py: Python<'_>,
+ ctx: Option<HashMap<String, String>>,
+ ) -> PyResult<Py<PyAny>> {
+ let mgr = self.clone_pathlock_manager();
+ let fs_ctx = build_fs_context(ctx);
+ let snapshot = self.run_scoped(py, fs_ctx, move || {
+ let mgr = mgr.clone();
+ async move { mgr.observe().await }
+ });
+ Python::attach(|py| {
+ let dict = PyDict::new(py);
+ dict.set_item("active_locks", snapshot.active_locks)?;
+ dict.set_item("waiting_locks", snapshot.waiting_locks)?;
+ dict.set_item("stale_locks_removed", snapshot.stale_locks_removed)?;
+ let conflicts = PyList::empty(py);
+ for c in &snapshot.conflicts {
+ let cd = PyDict::new(py);
+ cd.set_item("lock_path", &c.lock_path)?;
+ cd.set_item("conflicting_owner", &c.conflicting_owner)?;
+ cd.set_item("conflicting_kind", format!("{:?}", c.conflicting_kind))?;
+ conflicts.append(cd)?;
+ }
+ dict.set_item("conflicts", conflicts)?;
+ Ok(dict.into())
+ })
+ }
+
/// Get filesystem statistics.
///
/// Args:
@@ -1851,6 +2568,16 @@ impl RAGFSBindingClient {
#[pymodule]
fn ragfs_python(m: &Bound<'_, PyModule>) -> PyResult<()> {
m.add_class::<RAGFSBindingClient>()?;
+
+ // Import the Python business exception so native code raises the same type
+ // that `openviking.storage.errors` defines, enabling `except LockAcquisitionError`.
+ let py = m.py();
+ let errors_mod = py.import("openviking.storage.errors")?;
+ let exc_type: Py<PyType> = errors_mod.getattr("LockAcquisitionError")?.extract()?;
+ LOCK_ACQUISITION_ERROR_TYPE
+ .set(exc_type)
+ .map_err(|_| PyRuntimeError::new_err("LockAcquisitionError already initialized"))?;
+
Ok(())
}
diff --git a/crates/ragfs/Cargo.toml b/crates/ragfs/Cargo.toml
index d23af4e6c..3dad1781c 100644
--- a/crates/ragfs/Cargo.toml
+++ b/crates/ragfs/Cargo.toml
@@ -48,6 +48,7 @@ flate2 = "1.0"
# Path handling and filesystem
path-clean = "1.0"
+filelocks = "0.1.0"
# Data structures
radix_trie = "0.2"
@@ -86,6 +87,7 @@ globset = "0.4"
aes-gcm = "0.10"
hkdf = "0.12"
sha2 = "0.10"
+sha1 = "0.10"
rand = "0.8"
# Stream combinators for concurrent I/O
diff --git a/crates/ragfs/src/cache/policy.rs b/crates/ragfs/src/cache/policy.rs
index bbe21a5e7..a0131865c 100644
--- a/crates/ragfs/src/cache/policy.rs
+++ b/crates/ragfs/src/cache/policy.rs
@@ -1,5 +1,7 @@
//! Provider-independent cache eligibility rules.
+use crate::core::internal_names::is_hidden_runtime_lock_name;
+
const DEFAULT_MAX_CACHED_DIR_ENTRIES: usize = 4096;
/// Cache admission decision for a filesystem object.
@@ -135,7 +137,7 @@ impl CachePolicy {
}
let name = normalized.rsplit('/').next().unwrap_or("");
- if name == ".path.ovlock"
+ if is_hidden_runtime_lock_name(name)
|| name.ends_with(".lock")
|| name.ends_with(".lck")
|| matches!(
@@ -179,3 +181,20 @@ fn is_same_or_descendant(path: &str, prefix: &str) -> bool {
.strip_prefix(prefix)
.is_some_and(|suffix| suffix.starts_with('/'))
}
+
+#[cfg(test)]
+mod tests {
+ use super::*;
+
+ #[test]
+ fn runtime_lock_files_bypass_cache() {
+ let policy = CachePolicy::default();
+
+ for path in [
+ "/data/.path.ovlock",
+ "/data/.exact.ovlock.file.txt.0123456789abcdef",
+ ] {
+ assert_eq!(policy.file_decision(path, 32), CacheDecision::Bypass);
+ }
+ }
+}
diff --git a/crates/ragfs/src/cache/wrapper.rs b/crates/ragfs/src/cache/wrapper.rs
index d36151b46..2df524d6a 100644
--- a/crates/ragfs/src/cache/wrapper.rs
+++ b/crates/ragfs/src/cache/wrapper.rs
@@ -1063,7 +1063,7 @@ impl FileSystem for CachedFileSystem {
let key = self.file_key(&normalized);
self.cache_delete(&key, &normalized).await;
if offset == 0
- && matches!(flags, WriteFlag::Create | WriteFlag::Truncate)
+ && matches!(flags, WriteFlag::Create | WriteFlag::CreateNew | WriteFlag::Truncate)
&& self.policy.cache_file(&normalized, data.len())
&& !self.is_runtime_bypassed(&normalized).await
{
diff --git a/crates/ragfs/src/core/builder.rs b/crates/ragfs/src/core/builder.rs
index 1cf6f4c5e..da89b1cdc 100644
--- a/crates/ragfs/src/core/builder.rs
+++ b/crates/ragfs/src/core/builder.rs
@@ -6,6 +6,7 @@
//! `EncryptionWrappedFS` wrapper is removed from this builder.
//!
//! The top layer is always `StatsWrappedFS` so end-to-end timing (including crypto) is captured.
+//! When pathlock is enabled, `PathLockWrappedFS` sits between `StatsWrappedFS` and `MountableFS`.
use std::sync::Arc;
@@ -13,6 +14,11 @@ use super::filesystem::FileSystem;
use super::mountable::MountableFS;
use super::stats_wrapper::StatsWrappedFS;
+use crate::lock::{
+ FilesystemPathLockProvider, MemoryPathLockProvider, PathLockConfig, PathLockManager,
+ PathLockProvider, PathLockWrappedFS,
+};
+
#[cfg(feature = "s3")]
use crate::plugins::S3FSPlugin;
use crate::plugins::{
@@ -23,10 +29,20 @@ use crate::plugins::{
///
/// New capabilities are added as new optional sections here, without changing
/// `build_default_stack`'s signature.
-#[derive(Default)]
pub struct RagfsConfig {
/// Encryption section: `None` → plaintext stack; `Some` → per-backend encryption wrapping.
pub encryption: Option<EncryptionConfig>,
+ /// PathLock configuration. OpenViking always requires PathLock to be present.
+ pub pathlock: PathLockConfig,
+}
+
+impl Default for RagfsConfig {
+ fn default() -> Self {
+ Self {
+ encryption: None,
+ pathlock: PathLockConfig::default(),
+ }
+ }
}
/// Encryption section: root key fixed and immutable at construction time.
@@ -41,16 +57,30 @@ pub struct EncryptionConfig {
pub struct RagfsStack {
/// Mount manager (mount/unmount/list/stats/register_plugin live here).
pub mountable: Arc<MountableFS>,
- /// Data entry point: `Stats(Mountable)` — encryption is per-backend inside mount.
+ /// Data entry point: `Stats(PathLock(Mountable))`.
pub top: Arc<dyn FileSystem>,
+ /// PathLock manager. OpenViking always constructs the stack with PathLock enabled.
+ pub pathlock_manager: Arc<PathLockManager>,
}
/// Build the standard RAGFS stack.
///
/// Encryption config is forwarded to `MountableFS` so it can wrap individual backends
/// with `EncryptionWrappedFS` during `mount()`. The top is always `StatsWrappedFS`.
+/// PathLockWrappedFS is always inserted between stats and mountable.
pub async fn build_default_stack(config: RagfsConfig) -> RagfsStack {
let mountable = Arc::new(MountableFS::new());
+ build_stack_with_mountable(config, mountable).await
+}
+
+/// Build the standard wrapper stack around an existing mount manager.
+///
+/// This is used by the binding's cache-aware mountable so cache and non-cache
+/// construction share identical encryption and pathlock assembly.
+pub async fn build_stack_with_mountable(
+ config: RagfsConfig,
+ mountable: Arc<MountableFS>,
+) -> RagfsStack {
register_builtin_plugins(&mountable).await;
// Forward encryption config to MountableFS for per-backend wrapping.
@@ -60,11 +90,28 @@ pub async fn build_default_stack(config: RagfsConfig) -> RagfsStack {
.await;
}
- // MountableFS is the data entry point; encryption is applied inside mount().
- let top: Arc<dyn FileSystem> = Arc::new(StatsWrappedFS::with_arc(
- mountable.clone() as Arc<dyn FileSystem>
+ let provider: Arc<dyn PathLockProvider> = match config.pathlock.provider.as_str() {
+ "memory" => Arc::new(MemoryPathLockProvider::new()),
+ _ => Arc::new(FilesystemPathLockProvider::new(
+ mountable.clone() as Arc<dyn FileSystem>,
+ )),
+ };
+ let pathlock_manager = Arc::new(PathLockManager::new(
+ mountable.clone() as Arc<dyn FileSystem>,
+ provider,
+ config.pathlock.clone(),
));
- RagfsStack { mountable, top }
+ // Inject into MountableFS so EncryptionWrappedFS can use it for dual-path exact lock.
+ mountable
+ .set_pathlock_manager(pathlock_manager.clone())
+ .await;
+ let inner: Arc<dyn FileSystem> = Arc::new(PathLockWrappedFS::new(
+ pathlock_manager.clone(),
+ mountable.clone() as Arc<dyn FileSystem>,
+ ));
+
+ let top: Arc<dyn FileSystem> = Arc::new(StatsWrappedFS::with_arc(inner));
+ RagfsStack { mountable, top, pathlock_manager }
}
/// The single built-in plugin registration sequence (eliminates drift across call sites).
@@ -82,7 +129,7 @@ pub async fn register_builtin_plugins(fs: &MountableFS) {
#[cfg(test)]
mod tests {
use super::*;
- use crate::core::context::{FsContextInner, FS_CTX};
+ use crate::core::context::{FsContextInner, PathLockContext, FS_CTX};
use crate::core::{ConfigValue, PluginConfig, Result, WriteFlag};
use crate::crypto;
use std::collections::HashMap;
@@ -95,6 +142,20 @@ mod tests {
root_key: [4u8; 32],
provider_type: crypto::PROVIDER_LOCAL,
}),
+ ..RagfsConfig::default()
+ }
+ }
+
+ fn enc_pathlock_config() -> RagfsConfig {
+ RagfsConfig {
+ encryption: Some(EncryptionConfig {
+ root_key: [4u8; 32],
+ provider_type: crypto::PROVIDER_LOCAL,
+ }),
+ pathlock: PathLockConfig {
+ provider: "filesystem".to_string(),
+ lock_expire_secs: 300.0,
+ },
}
}
@@ -149,6 +210,107 @@ mod tests {
assert!(crypto::is_encrypted(&raw));
}
+ #[tokio::test]
+ async fn encrypted_stack_with_pathlock_does_not_reacquire_final_lock() {
+ let stack = build_default_stack(enc_pathlock_config()).await;
+ mount_mem(&stack).await;
+
+ let write = FS_CTX.scope(Arc::new(FsContextInner::new("tenant")), async {
+ stack
+ .top
+ .write("/mem/f", b"hello", 0, WriteFlag::Create)
+ .await
+ });
+ tokio::time::timeout(std::time::Duration::from_millis(200), write)
+ .await
+ .expect("encrypted write blocked on its own final-path lock")
+ .unwrap();
+
+ let rewrite = FS_CTX.scope(Arc::new(FsContextInner::new("tenant")), async {
+ stack
+ .top
+ .write("/mem/f", b"updated", 0, WriteFlag::Create)
+ .await
+ });
+ tokio::time::timeout(std::time::Duration::from_millis(200), rewrite)
+ .await
+ .expect("encrypted rewrite blocked on an unreleased lock token")
+ .unwrap();
+ }
+
+ #[tokio::test]
+ async fn encrypted_write_extends_outer_lease() {
+ let stack = build_default_stack(enc_pathlock_config()).await;
+ mount_mem(&stack).await;
+ let manager = &stack.pathlock_manager;
+ let outer = manager
+ .acquire_exact("/mem/f", std::time::Duration::ZERO, None)
+ .await
+ .unwrap();
+ let ctx = Arc::new(FsContextInner::with_pathlock(
+ "tenant",
+ PathLockContext {
+ lease_ref: Some(outer.lease.lease_ref.clone()),
+ disable_auto_pathlock: false,
+ },
+ ));
+
+ let write = FS_CTX.scope(ctx, async {
+ stack
+ .top
+ .write("/mem/f", b"hello", 0, WriteFlag::Create)
+ .await
+ });
+ tokio::time::timeout(std::time::Duration::from_millis(200), write)
+ .await
+ .expect("encrypted write blocked on its outer final-path lease")
+ .unwrap();
+
+ manager.release(&outer).await.unwrap();
+ }
+
+ #[tokio::test]
+ async fn encrypted_write_rejects_uncovered_outer_lease() {
+ let stack = build_default_stack(enc_pathlock_config()).await;
+ mount_mem(&stack).await;
+ let manager = &stack.pathlock_manager;
+ let outer = manager
+ .acquire_exact("/mem/other", std::time::Duration::ZERO, None)
+ .await
+ .unwrap();
+ let ctx = Arc::new(FsContextInner::with_pathlock(
+ "tenant",
+ PathLockContext {
+ lease_ref: Some(outer.lease.lease_ref.clone()),
+ disable_auto_pathlock: false,
+ },
+ ));
+
+ let error = FS_CTX
+ .scope(ctx, async {
+ stack
+ .top
+ .write("/mem/f", b"hello", 0, WriteFlag::Create)
+ .await
+ })
+ .await
+ .unwrap_err();
+
+ assert!(
+ error
+ .to_string()
+ .contains("does not cover the requested operation")
+ );
+ manager.release(&outer).await.unwrap();
+ }
+
+ #[tokio::test]
+ async fn default_stack_initializes_pathlock_manager() {
+ let stack = build_default_stack(RagfsConfig::default()).await;
+ let snapshot = stack.pathlock_manager.observe().await;
+ assert_eq!(snapshot.active_locks, 0);
+ }
+
#[tokio::test]
async fn plaintext_stack_has_no_encryption_layer() {
let stack = build_default_stack(RagfsConfig::default()).await;
diff --git a/crates/ragfs/src/core/context.rs b/crates/ragfs/src/core/context.rs
index 3f1f36339..3587a13e3 100644
--- a/crates/ragfs/src/core/context.rs
+++ b/crates/ragfs/src/core/context.rs
@@ -10,7 +10,8 @@
use std::sync::Arc;
-/// Immutable filesystem context snapshot. Currently carries only `account_id` (the tenant).
+/// Immutable filesystem context snapshot. Currently carries `account_id` (the tenant)
+/// and optional `PathLockContext`.
pub type FsContext = Arc<FsContextInner>;
tokio::task_local! {
@@ -18,10 +19,20 @@ tokio::task_local! {
pub static FS_CTX: FsContext;
}
+/// PathLock context carried in the FS context.
+#[derive(Clone, Debug, Default)]
+pub struct PathLockContext {
+ /// Lease reference string for an existing owned lease.
+ pub lease_ref: Option<String>,
+ /// When true, automatic PathLock consumers skip lock validation and acquisition.
+ pub disable_auto_pathlock: bool,
+}
+
/// Context payload (immutable). Fields are filled once at construction, then read-only.
#[derive(Clone, Debug)]
pub struct FsContextInner {
account_id: String,
+ pathlock: Option<PathLockContext>,
}
impl FsContextInner {
@@ -29,6 +40,18 @@ impl FsContextInner {
pub fn new(account_id: impl Into<String>) -> Self {
Self {
account_id: account_id.into(),
+ pathlock: None,
+ }
+ }
+
+ /// Construct a context with account_id and pathlock context.
+ pub fn with_pathlock(
+ account_id: impl Into<String>,
+ pathlock: PathLockContext,
+ ) -> Self {
+ Self {
+ account_id: account_id.into(),
+ pathlock: Some(pathlock),
}
}
@@ -36,6 +59,21 @@ impl FsContextInner {
pub fn account_id(&self) -> &str {
&self.account_id
}
+
+ /// PathLock context, if set.
+ pub fn pathlock(&self) -> Option<&PathLockContext> {
+ self.pathlock.as_ref()
+ }
+
+ /// Return a context copy that preserves identity and lease while disabling automatic PathLock.
+ pub fn with_auto_pathlock_disabled(&self) -> Self {
+ let mut pathlock = self.pathlock.clone().unwrap_or_default();
+ pathlock.disable_auto_pathlock = true;
+ Self {
+ account_id: self.account_id.clone(),
+ pathlock: Some(pathlock),
+ }
+ }
}
/// Read-only view over the current task-local context.
@@ -62,6 +100,23 @@ impl FsContextView {
.map(|c| c.account_id())
.filter(|account_id| !account_id.is_empty())
}
+
+ /// PathLock lease reference from the current context, or `None` if unset.
+ pub fn pathlock_lease_ref(&self) -> Option<&str> {
+ self.inner
+ .as_ref()
+ .and_then(|c| c.pathlock())
+ .and_then(|p| p.lease_ref.as_deref())
+ }
+
+ /// Whether auto pathlock is disabled in the current context.
+ pub fn disable_auto_pathlock(&self) -> bool {
+ self.inner
+ .as_ref()
+ .and_then(|c| c.pathlock())
+ .map(|p| p.disable_auto_pathlock)
+ .unwrap_or(false)
+ }
}
#[cfg(test)]
diff --git a/crates/ragfs/src/core/encryption_wrapper.rs b/crates/ragfs/src/core/encryption_wrapper.rs
index 163fb88a3..542e4dec9 100644
--- a/crates/ragfs/src/core/encryption_wrapper.rs
+++ b/crates/ragfs/src/core/encryption_wrapper.rs
@@ -17,6 +17,10 @@ use sha2::{Digest, Sha256};
use tracing::warn;
use crate::crypto;
+use crate::core::internal_names::is_hidden_runtime_lock_name;
+use crate::lock::{
+ AutoPathLockAction, PathLockKind, PathLockManager, PathLockRequest,
+};
use crate::shape::SHAPE_MANIFEST_PATH;
use super::context::FsContextView;
@@ -40,6 +44,10 @@ pub struct EncryptionWrappedFS {
account_keys: RwLock<HashMap<String, [u8; 32]>>,
/// Lazily-warmed temp root cache, keyed by temp_root path.
temp_root_ready: RwLock<HashMap<String, Instant>>,
+ /// PathLock manager for dual-path exact lock on encrypted writes.
+ pathlock_manager: Arc<PathLockManager>,
+ /// Backend mount prefix used to restore manager-visible backend paths.
+ backend_prefix: String,
}
impl EncryptionWrappedFS {
@@ -48,17 +56,37 @@ impl EncryptionWrappedFS {
&self.inner
}
- /// Construct an encryption layer over `inner`. Built only when a root key is configured.
- pub fn new(inner: Arc<dyn FileSystem>, root_key: [u8; 32], provider_type: u8) -> Self {
+ /// Construct an encryption layer with a pathlock manager for dual-path exact lock.
+ pub fn new(
+ inner: Arc<dyn FileSystem>,
+ root_key: [u8; 32],
+ provider_type: u8,
+ pathlock_manager: Arc<PathLockManager>,
+ backend_prefix: String,
+ ) -> Self {
Self {
inner,
root_key,
provider_type,
account_keys: RwLock::new(HashMap::new()),
temp_root_ready: RwLock::new(HashMap::new()),
+ pathlock_manager,
+ backend_prefix,
}
}
+ /// Convert one mount-relative path back to the manager's backend path space.
+ fn backend_lock_path(&self, path: &str) -> String {
+ if self.backend_prefix.is_empty() || self.backend_prefix == "/" {
+ return format!("/{}", path.trim_start_matches('/'));
+ }
+ format!(
+ "{}/{}",
+ self.backend_prefix.trim_end_matches('/'),
+ path.trim_start_matches('/')
+ )
+ }
+
/// Derive (and cache) the Account Key for `account_id` via HKDF (L2).
fn get_account_key(&self, account_id: &str) -> [u8; 32] {
if let Some(k) = self.account_keys.read().unwrap().get(account_id) {
@@ -106,6 +134,14 @@ impl EncryptionWrappedFS {
|| path.starts_with("/queue/")
|| path == "/serverinfo"
|| path.starts_with("/serverinfo/")
+ || Self::is_lock_sidecar(path)
+ }
+
+ /// Return true when `path` is a lock sidecar file that must bypass encryption
+ /// to preserve `CreateNew` atomicity.
+ fn is_lock_sidecar(path: &str) -> bool {
+ let name = path.rsplit_once('/').map(|(_, n)| n).unwrap_or(path);
+ is_hidden_runtime_lock_name(name)
}
/// Return true when one path points at the backend-shape manifest.
@@ -199,6 +235,47 @@ impl EncryptionWrappedFS {
Ok(())
}
+ /// Write the encrypted envelope to the temp path, retrying on transient errors.
+ async fn encrypted_write_inner(
+ &self,
+ path: &str,
+ temp_path: &str,
+ envelope: &[u8],
+ ) -> Result<u64> {
+ let written = match self
+ .inner
+ .write(temp_path, envelope, 0, WriteFlag::Create)
+ .await
+ {
+ Ok(written) => written,
+ Err(Error::NotFound(_)) => {
+ let temp_root = Self::encrypted_temp_root(path);
+ self.create_temp_root(&temp_root).await?;
+ self.inner
+ .write(temp_path, envelope, 0, WriteFlag::Create)
+ .await?
+ }
+ Err(Error::AlreadyExists(_)) => {
+ match self.inner.remove(temp_path).await {
+ Ok(()) | Err(Error::NotFound(_)) => {}
+ Err(err) => return Err(err),
+ }
+ self.inner
+ .write(temp_path, envelope, 0, WriteFlag::Create)
+ .await?
+ }
+ Err(err) => return Err(err),
+ };
+ if written != envelope.len() as u64 {
+ return Err(Error::internal(format!(
+ "encrypted temp write incomplete: wrote {} of {} bytes",
+ written,
+ envelope.len()
+ )));
+ }
+ Ok(written)
+ }
+
}
/// Slice `data` by `(offset, size)` with `size == 0` meaning "to end", matching plugin read semantics.
@@ -281,6 +358,8 @@ impl FileSystem for EncryptionWrappedFS {
let envelope = crypto::build_envelope(self.provider_type, &enc_key, &key_iv, &data_iv, &ct);
let temp_root = Self::encrypted_temp_root(path);
let temp_path = Self::encrypted_temp_path(path);
+
+ // Ensure temp root exists before acquiring locks (lock resolver needs stat).
let now = Instant::now();
let temp_root_ready = self
.temp_root_ready
@@ -291,39 +370,73 @@ impl FileSystem for EncryptionWrappedFS {
if !temp_root_ready {
self.create_temp_root(&temp_root).await?;
}
- let written = match self
- .inner
- .write(&temp_path, &envelope, 0, WriteFlag::Create)
+
+ // Acquire dual-path exact lock for the temp publish path and the final visible path.
+ let final_lock_path = self.backend_lock_path(path);
+ let temp_lock_path = self.backend_lock_path(&temp_path);
+ let final_request = PathLockRequest {
+ path: final_lock_path,
+ kind: PathLockKind::Exact,
+ };
+ let requests = vec![
+ PathLockRequest { path: temp_lock_path, kind: PathLockKind::Exact },
+ final_request.clone(),
+ ];
+ let action = self
+ .pathlock_manager
+ .resolve_auto_pathlock_action(&[final_request])
.await
- {
- Ok(written) => written,
- Err(Error::NotFound(_)) => {
- self.create_temp_root(&temp_root).await?;
- self.inner
- .write(&temp_path, &envelope, 0, WriteFlag::Create)
- .await?
- }
- Err(Error::AlreadyExists(_)) => {
- match self.inner.remove(&temp_path).await {
- Ok(()) | Err(Error::NotFound(_)) => {}
- Err(err) => return Err(err),
- }
- self.inner
- .write(&temp_path, &envelope, 0, WriteFlag::Create)
- .await?
+ .map_err(|error| {
+ Error::internal(format!("encrypted write lock context error: {error}"))
+ })?;
+ let lock_guard = match action {
+ AutoPathLockAction::Disabled => None,
+ AutoPathLockAction::Covered(outer) => {
+ let owner_capability = (
+ outer.lease.lease_ref.as_str(),
+ outer.ownership_ref.as_str(),
+ );
+ Some(
+ self.pathlock_manager
+ .acquire_batch(
+ &requests,
+ Duration::from_secs(1),
+ Some(owner_capability),
+ )
+ .await
+ .map_err(|error| {
+ Error::internal(format!("encrypted write lock error: {error}"))
+ })?,
+ )
}
- Err(err) => return Err(err),
+ AutoPathLockAction::Acquire => Some(
+ self.pathlock_manager
+ .acquire_batch(&requests, Duration::from_secs(1), None)
+ .await
+ .map_err(|error| {
+ Error::internal(format!("encrypted write lock error: {error}"))
+ })?,
+ ),
};
- if written != envelope.len() as u64 {
- return Err(Error::internal(format!(
- "encrypted temp write incomplete: wrote {} of {} bytes",
- written,
- envelope.len()
- )));
- }
- self.inner.replace(&temp_path, path).await?;
- Ok(written)
+ // Release lock on error. On success, release after replace.
+ let result = self.encrypted_write_inner(path, &temp_path, &envelope).await;
+ let replace_result = match result {
+ Ok(written) => self.inner.replace(&temp_path, path).await.map(|_| written),
+ Err(e) => Err(e),
+ };
+ // Release an acquired dual-path lock even if replace fails.
+ let release_result = match lock_guard.as_ref() {
+ Some(guard) => self.pathlock_manager.release(guard).await,
+ None => Ok(()),
+ };
+ match (replace_result, release_result) {
+ (Err(error), _) => Err(error),
+ (Ok(written), Ok(())) => Ok(written),
+ (Ok(_), Err(error)) => Err(Error::internal(format!(
+ "encrypted write lock release error: {error}"
+ ))),
+ }
}
async fn grep(
@@ -479,6 +592,9 @@ mod tests {
use crate::core::context::{FsContextInner, FS_CTX};
use crate::core::MountableFS;
use crate::core::PluginConfig;
+ use crate::lock::{
+ MemoryPathLockProvider, PathLockConfig, PathLockManager, PathLockProvider,
+ };
use crate::plugins::MemFSPlugin;
/// Build a memfs plugin config for encryption wrapper tests.
@@ -499,6 +615,18 @@ mod tests {
m
}
+ /// Build a PathLock manager for one test mount stack.
+ async fn memfs_pathlock_manager(stack: Arc<MountableFS>) -> Arc<PathLockManager> {
+ let provider: Arc<dyn PathLockProvider> = Arc::new(MemoryPathLockProvider::new());
+ let manager = Arc::new(PathLockManager::new(
+ stack.clone() as Arc<dyn FileSystem>,
+ provider,
+ PathLockConfig::default(),
+ ));
+ stack.set_pathlock_manager(manager.clone()).await;
+ manager
+ }
+
fn ctx(account: &str) -> Arc<FsContextInner> {
Arc::new(FsContextInner::new(account))
}
@@ -506,7 +634,14 @@ mod tests {
#[tokio::test]
async fn write_then_read_roundtrip_under_ctx() {
let inner = memfs_stack().await;
- let enc = EncryptionWrappedFS::new(inner, [9u8; 32], crypto::PROVIDER_LOCAL);
+ let manager = memfs_pathlock_manager(inner.clone()).await;
+ let enc = EncryptionWrappedFS::new(
+ inner,
+ [9u8; 32],
+ crypto::PROVIDER_LOCAL,
+ manager,
+ "/mem".to_string(),
+ );
FS_CTX
.scope(ctx("tenant-1"), async {
@@ -522,7 +657,14 @@ mod tests {
#[tokio::test]
async fn on_disk_bytes_are_ciphertext_with_envelope() {
let inner = memfs_stack().await;
- let enc = EncryptionWrappedFS::new(inner.clone(), [9u8; 32], crypto::PROVIDER_LOCAL);
+ let manager = memfs_pathlock_manager(inner.clone()).await;
+ let enc = EncryptionWrappedFS::new(
+ inner.clone(),
+ [9u8; 32],
+ crypto::PROVIDER_LOCAL,
+ manager,
+ "/mem".to_string(),
+ );
FS_CTX
.scope(ctx("tenant-1"), async {
@@ -541,7 +683,14 @@ mod tests {
#[tokio::test]
async fn read_without_account_id_errors() {
let inner = memfs_stack().await;
- let enc = EncryptionWrappedFS::new(inner.clone(), [9u8; 32], crypto::PROVIDER_LOCAL);
+ let manager = memfs_pathlock_manager(inner.clone()).await;
+ let enc = EncryptionWrappedFS::new(
+ inner.clone(),
+ [9u8; 32],
+ crypto::PROVIDER_LOCAL,
+ manager,
+ "/mem".to_string(),
+ );
// Seed an envelope first.
FS_CTX
.scope(ctx("tenant-1"), async {
@@ -558,7 +707,14 @@ mod tests {
#[tokio::test]
async fn read_offset_size_slicing() {
let inner = memfs_stack().await;
- let enc = EncryptionWrappedFS::new(inner, [1u8; 32], crypto::PROVIDER_LOCAL);
+ let manager = memfs_pathlock_manager(inner.clone()).await;
+ let enc = EncryptionWrappedFS::new(
+ inner,
+ [1u8; 32],
+ crypto::PROVIDER_LOCAL,
+ manager,
+ "/mem".to_string(),
+ );
FS_CTX
.scope(ctx("t"), async {
enc.write("/mem/a.txt", b"0123456789", 0, WriteFlag::Create)
@@ -574,7 +730,14 @@ mod tests {
#[tokio::test]
async fn grep_matches_encrypted_files() {
let inner = memfs_stack().await;
- let enc = EncryptionWrappedFS::new(inner, [2u8; 32], crypto::PROVIDER_LOCAL);
+ let manager = memfs_pathlock_manager(inner.clone()).await;
+ let enc = EncryptionWrappedFS::new(
+ inner,
+ [2u8; 32],
+ crypto::PROVIDER_LOCAL,
+ manager,
+ "/mem".to_string(),
+ );
FS_CTX
.scope(ctx("t"), async {
enc.write(
@@ -598,7 +761,14 @@ mod tests {
#[tokio::test]
async fn write_rejects_nonzero_offset() {
let inner = memfs_stack().await;
- let enc = EncryptionWrappedFS::new(inner, [2u8; 32], crypto::PROVIDER_LOCAL);
+ let manager = memfs_pathlock_manager(inner.clone()).await;
+ let enc = EncryptionWrappedFS::new(
+ inner,
+ [2u8; 32],
+ crypto::PROVIDER_LOCAL,
+ manager,
+ "/mem".to_string(),
+ );
FS_CTX
.scope(ctx("t"), async {
let r = enc.write("/mem/a.txt", b"x", 5, WriteFlag::Create).await;
@@ -610,7 +780,14 @@ mod tests {
#[tokio::test]
async fn create_writes_encrypted_empty_file() {
let inner = memfs_stack().await;
- let enc = EncryptionWrappedFS::new(inner.clone(), [2u8; 32], crypto::PROVIDER_LOCAL);
+ let manager = memfs_pathlock_manager(inner.clone()).await;
+ let enc = EncryptionWrappedFS::new(
+ inner.clone(),
+ [2u8; 32],
+ crypto::PROVIDER_LOCAL,
+ manager,
+ "/mem".to_string(),
+ );
FS_CTX
.scope(ctx("t"), async {
enc.create("/mem/empty.txt").await.unwrap();
@@ -626,7 +803,14 @@ mod tests {
#[tokio::test]
async fn cross_account_cannot_decrypt() {
let inner = memfs_stack().await;
- let enc = EncryptionWrappedFS::new(inner, [3u8; 32], crypto::PROVIDER_LOCAL);
+ let manager = memfs_pathlock_manager(inner.clone()).await;
+ let enc = EncryptionWrappedFS::new(
+ inner,
+ [3u8; 32],
+ crypto::PROVIDER_LOCAL,
+ manager,
+ "/mem".to_string(),
+ );
FS_CTX
.scope(ctx("acct-A"), async {
enc.write("/mem/a.txt", b"owned by A", 0, WriteFlag::Create)
@@ -644,7 +828,14 @@ mod tests {
#[tokio::test]
async fn write_rejects_append_flag() {
let inner = memfs_stack().await;
- let enc = EncryptionWrappedFS::new(inner, [4u8; 32], crypto::PROVIDER_LOCAL);
+ let manager = memfs_pathlock_manager(inner.clone()).await;
+ let enc = EncryptionWrappedFS::new(
+ inner,
+ [4u8; 32],
+ crypto::PROVIDER_LOCAL,
+ manager,
+ "/mem".to_string(),
+ );
FS_CTX
.scope(ctx("t"), async {
enc.write("/mem/a.txt", b"first", 0, WriteFlag::Create)
@@ -661,7 +852,14 @@ mod tests {
#[tokio::test]
async fn write_rejects_non_replacing_none_flag() {
let inner = memfs_stack().await;
- let enc = EncryptionWrappedFS::new(inner, [4u8; 32], crypto::PROVIDER_LOCAL);
+ let manager = memfs_pathlock_manager(inner.clone()).await;
+ let enc = EncryptionWrappedFS::new(
+ inner,
+ [4u8; 32],
+ crypto::PROVIDER_LOCAL,
+ manager,
+ "/mem".to_string(),
+ );
FS_CTX
.scope(ctx("t"), async {
enc.write("/mem/a.txt", b"first", 0, WriteFlag::Create)
@@ -676,7 +874,14 @@ mod tests {
#[tokio::test]
async fn rename_rejects_cross_account_paths() {
let inner = memfs_stack_at("/local").await;
- let enc = EncryptionWrappedFS::new(inner, [5u8; 32], crypto::PROVIDER_LOCAL);
+ let manager = memfs_pathlock_manager(inner.clone()).await;
+ let enc = EncryptionWrappedFS::new(
+ inner,
+ [5u8; 32],
+ crypto::PROVIDER_LOCAL,
+ manager,
+ "/local".to_string(),
+ );
let result = FS_CTX
.scope(ctx("acct-a"), async {
enc.mkdir("/local/acct-a", 0).await.unwrap();
@@ -694,7 +899,14 @@ mod tests {
#[tokio::test]
async fn write_replaces_stale_internal_temp_file_before_publish() {
let inner = memfs_stack().await;
- let enc = EncryptionWrappedFS::new(inner.clone(), [6u8; 32], crypto::PROVIDER_LOCAL);
+ let manager = memfs_pathlock_manager(inner.clone()).await;
+ let enc = EncryptionWrappedFS::new(
+ inner.clone(),
+ [6u8; 32],
+ crypto::PROVIDER_LOCAL,
+ manager,
+ "/mem".to_string(),
+ );
let temp_path =
"/mem/temp/.encrypt_stage/18d3740a61555bfecb941730d4b708dd3090a1b0ba2fcafe8c696d55c5e4b67a.encrypt";
diff --git a/crates/ragfs/src/core/filesystem.rs b/crates/ragfs/src/core/filesystem.rs
index e76044bf8..7a9c7965e 100644
--- a/crates/ragfs/src/core/filesystem.rs
+++ b/crates/ragfs/src/core/filesystem.rs
@@ -197,6 +197,52 @@ pub trait FileSystem: Send + Sync + Any {
/// * `Error::IsADirectory` - If the path points to a directory
async fn write(&self, path: &str, data: &[u8], offset: u64, flags: WriteFlag) -> Result<u64>;
+ /// Replace a file only when its full current content equals `expected`.
+ ///
+ /// # Arguments
+ /// * `path` - The path of the file to replace
+ /// * `expected` - Exact current file content required for the replacement
+ /// * `new_data` - New full file content
+ ///
+ /// # Returns
+ /// `true` when replaced, `false` when the file is missing or no longer matches.
+ ///
+ /// # Errors
+ /// Returns `Error::InvalidOperation` when the backend cannot provide a native
+ /// compare-and-write operation.
+ async fn compare_and_write(
+ &self,
+ path: &str,
+ expected: &[u8],
+ new_data: &[u8],
+ ) -> Result<bool> {
+ let _ = (expected, new_data);
+ Err(Error::invalid_operation(format!(
+ "compare_and_write is not supported: {}",
+ path
+ )))
+ }
+
+ /// Remove a file only when its full current content equals `expected`.
+ ///
+ /// # Arguments
+ /// * `path` - The path of the file to remove
+ /// * `expected` - Exact current file content required for removal
+ ///
+ /// # Returns
+ /// `true` when removed, `false` when the file is missing or no longer matches.
+ ///
+ /// # Errors
+ /// Returns `Error::InvalidOperation` when the backend cannot provide a native
+ /// compare-and-remove operation.
+ async fn compare_and_remove(&self, path: &str, expected: &[u8]) -> Result<bool> {
+ let _ = expected;
+ Err(Error::invalid_operation(format!(
+ "compare_and_remove is not supported: {}",
+ path
+ )))
+ }
+
/// List directory contents
///
/// # Arguments
@@ -210,6 +256,17 @@ pub trait FileSystem: Send + Sync + Any {
/// * `Error::NotADirectory` - If the path is not a directory
async fn read_dir(&self, path: &str) -> Result<Vec<FileInfo>>;
+ /// List directory contents without public internal-name filtering.
+ ///
+ /// # Arguments
+ /// * `path` - The directory path to list
+ ///
+ /// # Returns
+ /// Raw directory entries visible to filesystem internals.
+ async fn read_internal_dir(&self, path: &str) -> Result<Vec<FileInfo>> {
+ self.read_dir(path).await
+ }
+
/// Get file or directory metadata
///
/// # Arguments
@@ -1016,7 +1073,7 @@ mod tests {
let entries = root_tree(&fs, false, None, Some(1)).await;
assert_eq!(entries.len(), 2);
- assert_tree_names(&entries, &["a.txt", "sub"]);
+ assert_tree_names(&entries, &["sub", "a.txt"]);
}
#[tokio::test]
@@ -1081,8 +1138,8 @@ mod tests {
let entries = fs.tree_directory("/", false, None, None).await.unwrap();
assert_eq!(entries.len(), 2);
- assert_eq!(entries[0].path, "/a.txt");
- assert_eq!(entries[0].rel_path, "a.txt");
+ assert_eq!(entries[0].path, "/sub");
+ assert_eq!(entries[0].rel_path, "sub");
}
#[tokio::test]
diff --git a/crates/ragfs/src/core/internal_names.rs b/crates/ragfs/src/core/internal_names.rs
new file mode 100644
index 000000000..7d703cd22
--- /dev/null
+++ b/crates/ragfs/src/core/internal_names.rs
@@ -0,0 +1,27 @@
+//! Static built-in internal names shared across the RAGFS stack.
+//!
+//! Every module that references `.path.ovlock`, `.exact.ovlock.*`, `.redirect.json`,
+//! or `.sync_log.json` must import these constants from this single source of truth.
+//! There is no dynamic extension mechanism.
+
+/// Path-lock marker for directory-level locks.
+pub const PATH_LOCK_FILE: &str = ".path.ovlock";
+
+/// Prefix for exact (sidecar) lock files: `.exact.ovlock.<safe_name>.<sha1-prefix>`.
+pub const EXACT_LOCK_FILE_PREFIX: &str = ".exact.ovlock.";
+
+/// Multi-write redirect metadata file.
+pub const REDIRECT_FILE: &str = ".redirect.json";
+
+/// Multi-write sync-log metadata file.
+pub const SYNC_LOG_FILE: &str = ".sync_log.json";
+
+/// Returns `true` when `name` is a runtime path-lock file (`.path.ovlock` or `.exact.ovlock.*`).
+pub fn is_hidden_runtime_lock_name(name: &str) -> bool {
+ name == PATH_LOCK_FILE || name.starts_with(EXACT_LOCK_FILE_PREFIX)
+}
+
+/// Returns `true` when `name` is any hidden internal name (lock files, redirect, sync-log).
+pub fn is_hidden_internal_name(name: &str) -> bool {
+ is_hidden_runtime_lock_name(name) || name == REDIRECT_FILE || name == SYNC_LOG_FILE
+}
diff --git a/crates/ragfs/src/core/mod.rs b/crates/ragfs/src/core/mod.rs
index 6bc43e939..d2d72a989 100644
--- a/crates/ragfs/src/core/mod.rs
+++ b/crates/ragfs/src/core/mod.rs
@@ -13,6 +13,7 @@ pub mod encryption_wrapper;
pub mod errors;
pub mod filesystem;
pub mod glob;
+pub mod internal_names;
pub mod mountable;
pub mod multibackend_wrapper;
pub mod plugin;
@@ -23,10 +24,10 @@ pub mod types;
// Re-export commonly used types
pub use crate::multibackend::{FsContextResolver, MetaStateStore};
pub use builder::{
- build_default_stack, register_builtin_plugins, EncryptionConfig as BuilderEncryptionConfig,
- RagfsConfig, RagfsStack,
+ build_default_stack, build_stack_with_mountable, register_builtin_plugins,
+ EncryptionConfig as BuilderEncryptionConfig, RagfsConfig, RagfsStack,
};
-pub use context::{FsContext, FsContextInner, FsContextView, FS_CTX};
+pub use context::{FsContext, FsContextInner, FsContextView, PathLockContext, FS_CTX};
pub use encryption_wrapper::EncryptionWrappedFS;
pub use errors::{Error, Result};
pub use filesystem::FileSystem;
diff --git a/crates/ragfs/src/core/mountable.rs b/crates/ragfs/src/core/mountable.rs
index 9767214d2..ed1c66d1d 100644
--- a/crates/ragfs/src/core/mountable.rs
+++ b/crates/ragfs/src/core/mountable.rs
@@ -8,16 +8,19 @@ use async_trait::async_trait;
use radix_trie::{Trie, TrieCommon};
use serde_json::Value;
use std::collections::HashMap;
-use std::sync::Arc;
+use std::sync::{Arc, OnceLock};
+use std::time::Duration;
use tokio::sync::RwLock;
use tracing::warn;
+use crate::lock::{
+ AutoPathLockAction, PathLockKind, PathLockManager, PathLockRequest,
+};
use crate::multibackend::factory::build_multi_write_fs;
use crate::multibackend::types::MultiBackendBuildContext;
use crate::shape::validate::ensure_backend_shape;
-/// Python-side transaction path-lock marker — hidden in all listing/grep operations.
-const PATH_LOCK_FILE: &str = ".path.ovlock";
+use super::internal_names::is_hidden_internal_name;
use super::encryption_wrapper::EncryptionWrappedFS;
use super::errors::{Error, Result};
@@ -74,6 +77,9 @@ pub struct MountableFS {
encryption_root_key: RwLock<Option<[u8; 32]>>,
encryption_provider_type: RwLock<Option<u8>>,
+ /// PathLock manager, injected once before the stack starts serving requests.
+ pathlock_manager: OnceLock<Arc<PathLockManager>>,
+
/// Optional cache configuration shared by mounted filesystems.
#[cfg(feature = "cache")]
cache: Option<MountCacheConfig>,
@@ -143,6 +149,21 @@ impl MountableFS {
None
}
+ /// Return whether a mounted wrapper chain contains encryption-owned pathlock.
+ fn encryption_handles_pathlock_ref(fs: &dyn FileSystem) -> bool {
+ let any = fs as &dyn std::any::Any;
+ if any.downcast_ref::<EncryptionWrappedFS>().is_some() {
+ return true;
+ }
+ if let Some(multiwrite) = any.downcast_ref::<MultiWriteWrappedFS>() {
+ return multiwrite.encryption_handles_pathlock();
+ }
+ if let Some(stats) = any.downcast_ref::<StatsWrappedFS>() {
+ return Self::encryption_handles_pathlock_ref(stats.inner_fs().as_ref());
+ }
+ false
+ }
+
#[cfg(feature = "cache")]
fn as_cached(fs: &Arc<dyn FileSystem>) -> Option<&CachedFileSystem> {
let any = fs.as_ref() as &dyn std::any::Any;
@@ -165,6 +186,14 @@ impl MountableFS {
}
}
+ /// Return whether the mounted encryption wrapper owns pathlock for this path.
+ pub async fn encryption_handles_pathlock(&self, path: &str) -> bool {
+ let Ok((mount_info, _)) = self.find_mount(path).await else {
+ return false;
+ };
+ Self::encryption_handles_pathlock_ref(mount_info.fs.as_ref())
+ }
+
/// Query multi-write sync status for a mounted path.
pub async fn system_sync_status(&self, path: &str) -> Result<Value> {
let (mount_info, rel_path) = self.find_mount(path).await?;
@@ -188,6 +217,7 @@ impl MountableFS {
registry: Arc::new(RwLock::new(HashMap::new())),
encryption_root_key: RwLock::new(None),
encryption_provider_type: RwLock::new(None),
+ pathlock_manager: OnceLock::new(),
#[cfg(feature = "cache")]
cache: None,
}
@@ -208,6 +238,7 @@ impl MountableFS {
registry: Arc::new(RwLock::new(HashMap::new())),
encryption_root_key: RwLock::new(None),
encryption_provider_type: RwLock::new(None),
+ pathlock_manager: OnceLock::new(),
cache: Some(MountCacheConfig {
provider,
namespace,
@@ -226,6 +257,13 @@ impl MountableFS {
*self.encryption_provider_type.write().await = provider_type;
}
+ /// Set the pathlock manager for dual-path exact lock in EncryptionWrappedFS.
+ pub async fn set_pathlock_manager(&self, manager: Arc<PathLockManager>) {
+ if self.pathlock_manager.set(manager).is_err() {
+ panic!("pathlock manager must only be initialized once");
+ }
+ }
+
/// Get the encryption root key and provider type.
async fn get_encryption_config(&self) -> (Option<[u8; 32]>, Option<u8>) {
let rk = *self.encryption_root_key.read().await;
@@ -323,7 +361,18 @@ impl MountableFS {
config.name
)));
}
- Arc::new(EncryptionWrappedFS::new(storage_fs, rk, pt))
+ let pl_mgr = self
+ .pathlock_manager
+ .get()
+ .cloned()
+ .expect("pathlock manager must be initialized before mount");
+ Arc::new(EncryptionWrappedFS::new(
+ storage_fs,
+ rk,
+ pt,
+ pl_mgr,
+ normalized_path.clone(),
+ ))
}
_ => storage_fs,
}
@@ -396,6 +445,11 @@ impl MountableFS {
bc: &BackendsConfig,
) -> Result<MultiWriteWrappedFS> {
let (enc_root_key, enc_provider_type) = self.get_encryption_config().await;
+ let pathlock_manager = self
+ .pathlock_manager
+ .get()
+ .cloned()
+ .expect("pathlock manager must be initialized before multi-write mount");
build_multi_write_fs(
&self.registry,
config,
@@ -403,6 +457,8 @@ impl MountableFS {
MultiBackendBuildContext {
enc_root_key,
enc_provider_type,
+ pathlock_manager,
+ backend_prefix: config.mount_path.clone(),
},
)
.await
@@ -539,20 +595,66 @@ impl MountableFS {
return Ok(true);
}
- if let Some(multiwrite) = Self::as_multiwrite(&src_mount.fs) {
- return multiwrite
- .copy_within_primary(&src_rel_path, &dst_rel_path)
- .await;
+ let multiwrite = Self::as_multiwrite(&src_mount.fs);
+ let raw_backend = src_mount.raw_fs.clone();
+ if multiwrite.is_none() && raw_backend.is_none() {
+ return Ok(false);
}
- let Some(raw_backend) = src_mount.raw_fs.clone() else {
- return Ok(false);
+ let manager = self
+ .pathlock_manager
+ .get()
+ .cloned()
+ .expect("pathlock manager must be initialized before raw copy");
+ let request = PathLockRequest {
+ path: dst_path.to_string(),
+ kind: PathLockKind::Exact,
+ };
+ let auto_lease = match manager.resolve_auto_pathlock_action(&[request]).await {
+ Ok(AutoPathLockAction::Disabled | AutoPathLockAction::Covered(_)) => None,
+ Ok(AutoPathLockAction::Acquire) => Some(
+ manager
+ .acquire_exact(dst_path, Duration::ZERO, None)
+ .await
+ .map_err(|error| Error::internal(format!("lock error: {error}")))?,
+ ),
+ Err(error) => {
+ return Err(Error::internal(format!("lock lease error: {error}")));
+ }
};
- Self::copy_raw_within_mount(raw_backend, &src_rel_path, &dst_rel_path).await?;
- #[cfg(feature = "cache")]
- Self::invalidate_cache_after_raw_write(&dst_mount, &dst_rel_path).await;
- Ok(true)
+ let result = if let Some(multiwrite) = multiwrite {
+ multiwrite
+ .copy_within_primary(&src_rel_path, &dst_rel_path)
+ .await
+ } else {
+ match Self::copy_raw_within_mount(
+ raw_backend.expect("raw backend checked above"),
+ &src_rel_path,
+ &dst_rel_path,
+ )
+ .await
+ {
+ Ok(()) => {
+ #[cfg(feature = "cache")]
+ Self::invalidate_cache_after_raw_write(&dst_mount, &dst_rel_path).await;
+ Ok(true)
+ }
+ Err(error) => Err(error),
+ }
+ };
+
+ let release = match auto_lease {
+ Some(lease) => manager.release(&lease).await,
+ None => Ok(()),
+ };
+ match (result, release) {
+ (Err(error), _) => Err(error),
+ (Ok(performed), Ok(())) => Ok(performed),
+ (Ok(_), Err(error)) => Err(Error::internal(format!(
+ "copy lock release error: {error}"
+ ))),
+ }
}
/// Copy one file within one raw backend in bounded-size chunks.
@@ -762,10 +864,83 @@ impl FileSystem for MountableFS {
mount_info.fs.write(&rel_path, data, offset, flags).await
}
+ async fn compare_and_write(
+ &self,
+ path: &str,
+ expected: &[u8],
+ new_data: &[u8],
+ ) -> Result<bool> {
+ let (mount_info, rel_path) = self.find_mount(path).await?;
+ if let Some(multiwrite) = Self::as_multiwrite(&mount_info.fs) {
+ if rel_path
+ .rsplit('/')
+ .next()
+ .is_some_and(is_hidden_internal_name)
+ {
+ let raw = multiwrite.primary_raw_backend().ok_or_else(|| {
+ Error::internal(format!(
+ "raw backend is unavailable for mount '{}'",
+ mount_info.path
+ ))
+ })?;
+ let changed = raw.compare_and_write(&rel_path, expected, new_data).await?;
+ if changed {
+ #[cfg(feature = "cache")]
+ Self::invalidate_cache_after_raw_write(&mount_info, &rel_path).await;
+ }
+ return Ok(changed);
+ }
+ }
+ let raw = Self::raw_backend_for_mount(&mount_info, "compare_and_write")?;
+ let changed = raw.compare_and_write(&rel_path, expected, new_data).await?;
+ if changed {
+ #[cfg(feature = "cache")]
+ Self::invalidate_cache_after_raw_write(&mount_info, &rel_path).await;
+ }
+ Ok(changed)
+ }
+
+ async fn compare_and_remove(&self, path: &str, expected: &[u8]) -> Result<bool> {
+ let (mount_info, rel_path) = self.find_mount(path).await?;
+ if let Some(multiwrite) = Self::as_multiwrite(&mount_info.fs) {
+ if rel_path
+ .rsplit('/')
+ .next()
+ .is_some_and(is_hidden_internal_name)
+ {
+ let raw = multiwrite.primary_raw_backend().ok_or_else(|| {
+ Error::internal(format!(
+ "raw backend is unavailable for mount '{}'",
+ mount_info.path
+ ))
+ })?;
+ let changed = raw.compare_and_remove(&rel_path, expected).await?;
+ if changed {
+ #[cfg(feature = "cache")]
+ Self::invalidate_cache_after_raw_write(&mount_info, &rel_path).await;
+ }
+ return Ok(changed);
+ }
+ }
+ let raw = Self::raw_backend_for_mount(&mount_info, "compare_and_remove")?;
+ let changed = raw.compare_and_remove(&rel_path, expected).await?;
+ if changed {
+ #[cfg(feature = "cache")]
+ Self::invalidate_cache_after_raw_write(&mount_info, &rel_path).await;
+ }
+ Ok(changed)
+ }
+
async fn read_dir(&self, path: &str) -> Result<Vec<FileInfo>> {
+ let mut entries = self.read_internal_dir(path).await?;
+ entries.retain(|entry| !is_hidden_internal_name(&entry.name));
+ sort_directory_entries(&mut entries);
+ Ok(entries)
+ }
+
+ async fn read_internal_dir(&self, path: &str) -> Result<Vec<FileInfo>> {
let (mount_info, rel_path) = self.find_mount(path).await?;
- let mut entries = mount_info.fs.read_dir(&rel_path).await?;
- entries.retain(|e| e.name != PATH_LOCK_FILE);
+ let mut entries = mount_info.fs.read_internal_dir(&rel_path).await?;
sort_directory_entries(&mut entries);
Ok(entries)
}
@@ -861,12 +1036,12 @@ impl FileSystem for MountableFS {
)
.await?;
- // Filter out path-lock markers.
+ // Filter out internal files from public search results.
result.matches.retain(|m| {
m.file
.rsplit('/')
.next()
- .map_or(true, |name| name != PATH_LOCK_FILE)
+ .map_or(true, |name| !is_hidden_internal_name(name))
});
result.count = result.matches.len();
Ok(result)
@@ -902,12 +1077,12 @@ impl FileSystem for MountableFS {
}
}
- // Filter out path-lock markers.
+ // Filter out internal files from public tree results.
entries.retain(|e| {
e.path
.rsplit('/')
.next()
- .map_or(true, |name| name != PATH_LOCK_FILE)
+ .map_or(true, |name| !is_hidden_internal_name(name))
});
Ok(entries)
@@ -957,7 +1132,7 @@ impl FileSystem for MountableFS {
.path
.rsplit('/')
.next()
- .map_or(true, |name| name != PATH_LOCK_FILE)
+ .map_or(true, |name| !is_hidden_internal_name(name))
});
Ok(page)
@@ -1263,6 +1438,32 @@ mod tests {
mfs
}
+ /// Create a MountableFS backed by the real in-memory plugin.
+ async fn mounted_memfs(mount_path: &str) -> MountableFS {
+ use crate::plugins::MemFSPlugin;
+
+ let mfs = MountableFS::new();
+ mfs.register_plugin(MemFSPlugin).await;
+ mfs.mount(test_config("memfs", mount_path)).await.unwrap();
+ mfs
+ }
+
+ /// Create a cache-enabled MountableFS backed by the real in-memory plugin.
+ #[cfg(feature = "cache")]
+ async fn mounted_cached_memfs(namespace: &str, mount_path: &str) -> MountableFS {
+ use crate::cache::{CacheNamespace, CachePolicy, MemoryCacheProvider};
+ use crate::plugins::MemFSPlugin;
+
+ let mfs = MountableFS::with_cache(
+ Arc::new(MemoryCacheProvider::new()),
+ CacheNamespace::new(namespace),
+ CachePolicy::default(),
+ );
+ mfs.register_plugin(MemFSPlugin).await;
+ mfs.mount(test_config("memfs", mount_path)).await.unwrap();
+ mfs
+ }
+
/// Create a MountableFS with two mounted mock plugins.
async fn mounted_two_mocks() -> MountableFS {
let mfs = MountableFS::new();
@@ -1273,6 +1474,22 @@ mod tests {
mfs
}
+ /// Attach a test pathlock manager so multi-write mounts can be constructed.
+ async fn with_test_pathlock_manager(mfs: Arc<MountableFS>) -> Arc<MountableFS> {
+ use crate::lock::{
+ MemoryPathLockProvider, PathLockConfig, PathLockManager, PathLockProvider,
+ };
+
+ let provider: Arc<dyn PathLockProvider> = Arc::new(MemoryPathLockProvider::new());
+ let manager = Arc::new(PathLockManager::new(
+ mfs.clone() as Arc<dyn FileSystem>,
+ provider,
+ PathLockConfig::default(),
+ ));
+ mfs.set_pathlock_manager(manager).await;
+ mfs
+ }
+
#[test]
fn test_normalize_path() {
assert_eq!(normalize_path("/test"), "/test");
@@ -1284,7 +1501,7 @@ mod tests {
#[tokio::test]
async fn test_mountable_fs_creation() {
- let mfs = MountableFS::new();
+ let mfs = Arc::new(MountableFS::new());
let mounts = mfs.list_mounts().await;
assert!(mounts.is_empty());
}
@@ -1393,6 +1610,55 @@ mod tests {
);
}
+ #[tokio::test]
+ async fn copy_within_mount_rejects_uncovered_lease() {
+ use crate::core::{FsContextInner, PathLockContext, FS_CTX};
+ use crate::lock::{
+ MemoryPathLockProvider, PathLockConfig, PathLockManager, PathLockProvider,
+ };
+ use crate::plugins::MemFSPlugin;
+
+ let mfs = Arc::new(MountableFS::new());
+ mfs.register_plugin(MemFSPlugin).await;
+ mfs.mount(test_config("memfs", "/local")).await.unwrap();
+ mfs.mkdir("/local/src", 0o755).await.unwrap();
+ mfs.mkdir("/local/dst", 0o755).await.unwrap();
+ mfs.write("/local/src/a.md", b"content", 0, WriteFlag::Create)
+ .await
+ .unwrap();
+ let provider: Arc<dyn PathLockProvider> = Arc::new(MemoryPathLockProvider::new());
+ let manager = Arc::new(PathLockManager::new(
+ mfs.clone() as Arc<dyn FileSystem>,
+ provider,
+ PathLockConfig::default(),
+ ));
+ mfs.set_pathlock_manager(manager.clone()).await;
+ let outer = manager
+ .acquire_exact("/local/dst", std::time::Duration::ZERO, None)
+ .await
+ .unwrap();
+ let ctx = Arc::new(FsContextInner::with_pathlock(
+ "tenant",
+ PathLockContext {
+ lease_ref: Some(outer.lease.lease_ref.clone()),
+ disable_auto_pathlock: false,
+ },
+ ));
+
+ let result = FS_CTX
+ .scope(ctx, async {
+ mfs.copy_within_mount("/local/src/a.md", "/local/dst/a.md")
+ .await
+ })
+ .await;
+
+ assert!(result
+ .unwrap_err()
+ .to_string()
+ .contains("does not cover the requested operation"));
+ manager.release(&outer).await.unwrap();
+ }
+
#[cfg(feature = "cache")]
#[tokio::test]
async fn copy_within_mount_overwrite_invalidates_cached_destination() {
@@ -1449,16 +1715,27 @@ mod tests {
async fn encrypted_mount_caches_ciphertext_below_account_validation() {
use crate::cache::{CacheNamespace, CachePolicy, CacheProvider, MemoryCacheProvider};
use crate::core::{FsContextInner, FS_CTX};
+ use crate::lock::{
+ MemoryPathLockProvider, PathLockConfig, PathLockManager, PathLockProvider,
+ };
use crate::plugins::MemFSPlugin;
- let provider = Arc::new(MemoryCacheProvider::new());
- let mfs = MountableFS::with_cache(
- provider.clone(),
+ let cache_provider = Arc::new(MemoryCacheProvider::new());
+ let mfs = Arc::new(MountableFS::with_cache(
+ cache_provider.clone(),
CacheNamespace::new("encrypted-mount-test"),
CachePolicy::default(),
- );
+ ));
mfs.register_plugin(MemFSPlugin).await;
mfs.set_encryption_config(Some([9u8; 32]), Some(1)).await;
+ let pathlock_provider: Arc<dyn PathLockProvider> =
+ Arc::new(MemoryPathLockProvider::new());
+ let manager = Arc::new(PathLockManager::new(
+ mfs.clone() as Arc<dyn FileSystem>,
+ pathlock_provider,
+ PathLockConfig::default(),
+ ));
+ mfs.set_pathlock_manager(manager).await;
mfs.mount(test_config("memfs", "/local")).await.unwrap();
mfs.mkdir("/local/shared", 0o755).await.unwrap();
@@ -1496,13 +1773,13 @@ mod tests {
"missing account context must not receive cached plaintext"
);
- let file_key = provider
+ let file_key = cache_provider
.keys()
.await
.into_iter()
.find(|key| key.contains(":file:"))
.expect("encrypted read should populate one file cache object");
- let encoded = provider
+ let encoded = cache_provider
.get(&file_key)
.await
.unwrap()
@@ -1524,17 +1801,27 @@ mod tests {
#[tokio::test]
async fn encrypted_multiwrite_mount_does_not_install_plaintext_cache() {
use crate::cache::{CacheNamespace, CachePolicy, MemoryCacheProvider};
+ use crate::lock::{
+ MemoryPathLockProvider, PathLockConfig, PathLockManager, PathLockProvider,
+ };
+ use crate::plugins::MemFSPlugin;
- let mfs = MountableFS::with_cache(
+ let mfs = Arc::new(MountableFS::with_cache(
Arc::new(MemoryCacheProvider::new()),
CacheNamespace::new("encrypted-multiwrite-test"),
CachePolicy::default(),
- );
- mfs.register_plugin(MockPlugin::new("primary")).await;
- mfs.register_plugin(MockPlugin::new("backupfs")).await;
+ ));
+ mfs.register_plugin(MemFSPlugin).await;
mfs.set_encryption_config(Some([9u8; 32]), Some(1)).await;
+ let provider: Arc<dyn PathLockProvider> = Arc::new(MemoryPathLockProvider::new());
+ let manager = Arc::new(PathLockManager::new(
+ mfs.clone() as Arc<dyn FileSystem>,
+ provider,
+ PathLockConfig::default(),
+ ));
+ mfs.set_pathlock_manager(manager).await;
- let mut config = multiwrite_test_config("primary", "backupfs", "/local");
+ let mut config = multiwrite_test_config("memfs", "memfs", "/local");
config.server_encryption_enabled = true;
config.primary_encryption_enabled = true;
mfs.mount(config).await.unwrap();
@@ -1603,7 +1890,7 @@ mod tests {
#[tokio::test]
async fn test_mount_duplicate_error() {
- let mfs = MountableFS::new();
+ let mfs = Arc::new(MountableFS::new());
mfs.register_plugin(MockPlugin::new("mock")).await;
let config = test_config("mock", "/mock");
@@ -1857,7 +2144,7 @@ mod tests {
#[tokio::test]
async fn test_build_multi_write_fs_rejects_primary_encryption_disable() {
- let mfs = MountableFS::new();
+ let mfs = with_test_pathlock_manager(Arc::new(MountableFS::new())).await;
mfs.register_plugin(MockPlugin::new("primary")).await;
mfs.register_plugin(MockPlugin::new("backupfs")).await;
mfs.set_encryption_config(Some([7u8; 32]), Some(1)).await;
@@ -1896,9 +2183,66 @@ mod tests {
assert!(matches!(result.err(), Some(Error::Config(_))));
}
+ #[tokio::test]
+ async fn encrypted_multiwrite_reports_pathlock_ownership() {
+ use crate::core::{FsContextInner, PathLockContext, FS_CTX};
+ use crate::lock::{
+ MemoryPathLockProvider, PathLockConfig, PathLockManager, PathLockProvider,
+ };
+ use crate::plugins::MemFSPlugin;
+
+ let mfs = Arc::new(MountableFS::new());
+ mfs.register_plugin(MemFSPlugin).await;
+ mfs.set_encryption_config(Some([7u8; 32]), Some(1)).await;
+ let provider: Arc<dyn PathLockProvider> = Arc::new(MemoryPathLockProvider::new());
+ let manager = Arc::new(PathLockManager::new(
+ mfs.clone() as Arc<dyn FileSystem>,
+ provider,
+ PathLockConfig::default(),
+ ));
+ mfs.set_pathlock_manager(manager.clone()).await;
+
+ let mut config = multiwrite_test_config("memfs", "memfs", "/local");
+ config.server_encryption_enabled = true;
+ config.primary_encryption_enabled = true;
+ mfs.mount(config).await.unwrap();
+
+ assert!(mfs.encryption_handles_pathlock("/local/file.txt").await);
+
+ let outer_ctx = Arc::new(FsContextInner::new("tenant"));
+ let outer = FS_CTX
+ .scope(outer_ctx, async {
+ manager
+ .acquire_exact("/local/tenant/file.txt", std::time::Duration::ZERO, None)
+ .await
+ })
+ .await
+ .unwrap();
+ let ctx = Arc::new(FsContextInner::with_pathlock(
+ "tenant",
+ PathLockContext {
+ lease_ref: Some(outer.lease.lease_ref.clone()),
+ disable_auto_pathlock: false,
+ },
+ ));
+ FS_CTX
+ .scope(ctx, async {
+ mfs.write(
+ "/local/tenant/file.txt",
+ b"content",
+ 0,
+ WriteFlag::Create,
+ )
+ .await
+ })
+ .await
+ .unwrap();
+ manager.release(&outer).await.unwrap();
+ }
+
#[tokio::test]
async fn test_build_multi_write_fs_rejects_exclude_target_field() {
- let mfs = MountableFS::new();
+ let mfs = with_test_pathlock_manager(Arc::new(MountableFS::new())).await;
mfs.register_plugin(MockPlugin::new("primary")).await;
mfs.register_plugin(MockPlugin::new("backupfs")).await;
@@ -1940,7 +2284,7 @@ mod tests {
#[tokio::test]
async fn test_build_multi_write_fs_rejects_reserved_primary_backup_name() {
- let mfs = MountableFS::new();
+ let mfs = with_test_pathlock_manager(Arc::new(MountableFS::new())).await;
mfs.register_plugin(MockPlugin::new("primary")).await;
mfs.register_plugin(MockPlugin::new("backupfs")).await;
@@ -1979,11 +2323,23 @@ mod tests {
#[tokio::test]
async fn test_single_backend_mount_wraps_stats_outside_encryption() {
- let mfs = MountableFS::new();
- mfs.register_plugin(MockPlugin::new("mock")).await;
+ use crate::lock::{
+ MemoryPathLockProvider, PathLockConfig, PathLockManager, PathLockProvider,
+ };
+ use crate::plugins::MemFSPlugin;
+
+ let mfs = Arc::new(MountableFS::new());
+ mfs.register_plugin(MemFSPlugin).await;
mfs.set_encryption_config(Some([9u8; 32]), Some(1)).await;
+ let provider: Arc<dyn PathLockProvider> = Arc::new(MemoryPathLockProvider::new());
+ let manager = Arc::new(PathLockManager::new(
+ mfs.clone() as Arc<dyn FileSystem>,
+ provider,
+ PathLockConfig::default(),
+ ));
+ mfs.set_pathlock_manager(manager).await;
- mfs.mount(test_config("mock", "/mock")).await.unwrap();
+ mfs.mount(test_config("memfs", "/mock")).await.unwrap();
let mounts = mfs.mounts.read().await;
let mount_info = mounts.get("/mock").expect("mounted entry should exist");
@@ -2000,7 +2356,7 @@ mod tests {
#[tokio::test]
async fn test_multiwrite_mount_wraps_stats_outside_multiwrite() {
- let mfs = MountableFS::new();
+ let mfs = with_test_pathlock_manager(Arc::new(MountableFS::new())).await;
mfs.register_plugin(MockPlugin::new("primary")).await;
mfs.register_plugin(MockPlugin::new("backupfs")).await;
@@ -2023,7 +2379,7 @@ mod tests {
#[tokio::test]
async fn test_multiwrite_raw_access_is_rejected() {
- let mfs = MountableFS::new();
+ let mfs = with_test_pathlock_manager(Arc::new(MountableFS::new())).await;
mfs.register_plugin(MockPlugin::new("primary")).await;
mfs.register_plugin(MockPlugin::new("backupfs")).await;
@@ -2043,7 +2399,7 @@ mod tests {
#[tokio::test]
async fn test_mountable_multiwrite_admin_smoke() {
- let mfs = MountableFS::new();
+ let mfs = with_test_pathlock_manager(Arc::new(MountableFS::new())).await;
mfs.register_plugin(MockPlugin::new("primary")).await;
mfs.register_plugin(MockPlugin::new("backupfs")).await;
diff --git a/crates/ragfs/src/core/multibackend_wrapper.rs b/crates/ragfs/src/core/multibackend_wrapper.rs
index 0d204dba1..db2f7e1ef 100644
--- a/crates/ragfs/src/core/multibackend_wrapper.rs
+++ b/crates/ragfs/src/core/multibackend_wrapper.rs
@@ -19,6 +19,7 @@ use serde_json::Value;
use tokio::sync::{Mutex, Notify};
use super::context::{FsContext, FS_CTX};
+use super::encryption_wrapper::EncryptionWrappedFS;
use super::errors::{Error, Result};
use super::filesystem::{normalize_prefix_path, relative_match_file, FileSystem};
use super::types::{
@@ -29,6 +30,7 @@ use super::types::{
use crate::core::glob::{
compare_rel_paths, decode_offset_token, encode_offset_token, PreparedGlob,
};
+use crate::core::internal_names::is_hidden_internal_name;
use crate::multibackend::meta::{
current_required_ctx, file_name, parent_dir, DefaultFsContextResolver, FsContextResolver,
MetaStateStore, PathSerializer, MULTIWRITE_INTERNAL_NAMES,
@@ -581,6 +583,17 @@ impl MultiWriteWrappedFS {
ctx_resolver: Arc::new(DefaultFsContextResolver),
}
}
+
+ /// Return the raw primary backend for mount-level internal-name operations.
+ pub(crate) fn primary_raw_backend(&self) -> Option<Arc<dyn FileSystem>> {
+ self.inner.primary().raw_backend.clone()
+ }
+
+ /// Return whether encrypted backends own dual-path PathLock acquisition.
+ pub(crate) fn encryption_handles_pathlock(&self) -> bool {
+ let any = self.inner.primary().backend.as_ref() as &dyn std::any::Any;
+ any.downcast_ref::<EncryptionWrappedFS>().is_some()
+ }
}
impl Inner {
@@ -1290,6 +1303,9 @@ impl MultiWriteWrappedFS {
#[async_trait]
impl FileSystem for MultiWriteWrappedFS {
async fn create(&self, path: &str) -> Result<()> {
+ if is_hidden_internal_name(file_name(path)) {
+ return self.inner.primary().backend.create(path).await;
+ }
self.execute_simple_write(path, 0, Some(SyncOp::Create), |fs, path| async move {
fs.create(&path).await
})
@@ -1307,6 +1323,9 @@ impl FileSystem for MultiWriteWrappedFS {
}
async fn remove(&self, path: &str) -> Result<()> {
+ if is_hidden_internal_name(file_name(path)) {
+ return self.inner.primary().backend.remove(path).await;
+ }
self.execute_simple_write(path, 0, Some(SyncOp::Remove), |fs, path| async move {
fs.remove(&path).await
})
@@ -1314,6 +1333,9 @@ impl FileSystem for MultiWriteWrappedFS {
}
async fn remove_all(&self, path: &str) -> Result<()> {
+ if is_hidden_internal_name(file_name(path)) {
+ return self.inner.primary().backend.remove_all(path).await;
+ }
self.execute_simple_write(path, 0, Some(SyncOp::RemoveAll), |fs, path| async move {
fs.remove_all(&path).await
})
@@ -1321,6 +1343,9 @@ impl FileSystem for MultiWriteWrappedFS {
}
async fn read(&self, path: &str, offset: u64, size: u64) -> Result<Vec<u8>> {
+ if is_hidden_internal_name(file_name(path)) {
+ return self.inner.primary().backend.read(path, offset, size).await;
+ }
if let Some(fs) = self.inner.resolve_read_backend(path).await {
return fs.read(path, offset, size).await;
}
@@ -1328,6 +1353,14 @@ impl FileSystem for MultiWriteWrappedFS {
}
async fn write(&self, path: &str, data: &[u8], offset: u64, flags: WriteFlag) -> Result<u64> {
+ if is_hidden_internal_name(file_name(path)) {
+ return self
+ .inner
+ .primary()
+ .backend
+ .write(path, data, offset, flags)
+ .await;
+ }
let inner = &self.inner;
let data_len = data.len() as u64;
let path_owned = path.to_string();
@@ -1383,6 +1416,9 @@ impl FileSystem for MultiWriteWrappedFS {
}
async fn stat(&self, path: &str) -> Result<FileInfo> {
+ if is_hidden_internal_name(file_name(path)) {
+ return self.inner.primary().backend.stat(path).await;
+ }
if let Some(fs) = self.inner.resolve_read_backend(path).await {
return fs.stat(path).await;
}
@@ -1390,6 +1426,11 @@ impl FileSystem for MultiWriteWrappedFS {
}
async fn rename(&self, old_path: &str, new_path: &str) -> Result<()> {
+ if is_hidden_internal_name(file_name(old_path))
+ || is_hidden_internal_name(file_name(new_path))
+ {
+ return self.inner.primary().backend.rename(old_path, new_path).await;
+ }
let ctx = current_required_ctx()?;
let inner = &self.inner;
let old_owned = old_path.to_string();
@@ -1431,6 +1472,9 @@ impl FileSystem for MultiWriteWrappedFS {
}
async fn chmod(&self, path: &str, mode: u32) -> Result<()> {
+ if is_hidden_internal_name(file_name(path)) {
+ return self.inner.primary().backend.chmod(path, mode).await;
+ }
self.execute_simple_write(
path,
0,
@@ -1441,6 +1485,9 @@ impl FileSystem for MultiWriteWrappedFS {
}
async fn truncate(&self, path: &str, size: u64) -> Result<()> {
+ if is_hidden_internal_name(file_name(path)) {
+ return self.inner.primary().backend.truncate(path, size).await;
+ }
self.execute_simple_write(
path,
size,
diff --git a/crates/ragfs/src/core/types.rs b/crates/ragfs/src/core/types.rs
index 767091b0b..35d9f64f5 100644
--- a/crates/ragfs/src/core/types.rs
+++ b/crates/ragfs/src/core/types.rs
@@ -187,9 +187,16 @@ impl FileInfo {
/// Write operation flags
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
pub enum WriteFlag {
- /// Create new file or truncate existing
+ /// Create new file or truncate existing.
+ ///
+ /// Follows POSIX `O_CREAT` / Rust `OpenOptions::create(true)` convention:
+ /// create-or-open (non-exclusive). For exclusive create-if-absent, use
+ /// `CreateNew` (POSIX `O_CREAT | O_EXCL` / Rust `create_new(true)`).
Create,
+ /// Create new file, fail if already exists
+ CreateNew,
+
/// Append to existing file
Append,
diff --git a/crates/ragfs/src/git/enumerate.rs b/crates/ragfs/src/git/enumerate.rs
index fc2a287a6..cd2a77c73 100644
--- a/crates/ragfs/src/git/enumerate.rs
+++ b/crates/ragfs/src/git/enumerate.rs
@@ -14,6 +14,8 @@
//! L0/L1 derived files (`.abstract.md`, `.overview.md`, `.relations.json`)
//! are intentionally KEPT — design §4.2 says they belong in snapshots.
+use crate::core::internal_names::{is_hidden_runtime_lock_name, PATH_LOCK_FILE};
+
use std::sync::Arc;
use crate::core::filesystem::FileSystem;
@@ -47,11 +49,12 @@ pub fn prune_path(rel: &str) -> bool {
return true;
}
- // Rule 2: any segment equals or starts with ".path.ovlock"
- for seg in &segments {
- if seg.starts_with(".path.ovlock") {
- return true;
- }
+ // Rule 2: any segment is a runtime path-lock file.
+ if segments
+ .iter()
+ .any(|segment| segment.starts_with(PATH_LOCK_FILE) || is_hidden_runtime_lock_name(segment))
+ {
+ return true;
}
// Rule 3a: any intermediate segment named exactly "embedding_cache"
@@ -389,6 +392,9 @@ mod tests {
assert!(prune_path("upload/x"));
assert!(prune_path("resources/.path.ovlock"));
assert!(prune_path(".path.ovlock"));
+ assert!(prune_path(
+ "resources/.exact.ovlock.file.txt.0123456789abcdef"
+ ));
assert!(prune_path("resources/x.faiss"));
assert!(prune_path("resources/x.index"));
assert!(prune_path("resources/embedding_cache/v.bin"));
diff --git a/crates/ragfs/src/git/service.rs b/crates/ragfs/src/git/service.rs
index c83488fec..3b583f745 100644
--- a/crates/ragfs/src/git/service.rs
+++ b/crates/ragfs/src/git/service.rs
@@ -1303,6 +1303,8 @@ impl GitService {
Err(e) => failed_deletes.push((path, e.to_string())),
}
}
+ written_paths.sort();
+ deleted_paths.sort();
let written_actual = written_paths.len();
let deleted_actual = deleted_paths.len();
diff --git a/crates/ragfs/src/lib.rs b/crates/ragfs/src/lib.rs
index 082e9b4e1..06fad00b8 100644
--- a/crates/ragfs/src/lib.rs
+++ b/crates/ragfs/src/lib.rs
@@ -33,6 +33,7 @@
pub mod cache;
pub mod core;
pub mod crypto;
+pub mod lock;
pub mod multibackend;
pub mod git;
pub mod plugins;
diff --git a/crates/ragfs/src/lock/codec.rs b/crates/ragfs/src/lock/codec.rs
new file mode 100644
index 000000000..45d7c5bdf
--- /dev/null
+++ b/crates/ragfs/src/lock/codec.rs
@@ -0,0 +1,103 @@
+//! Lock token encoder/decoder.
+//!
+//! Wire format: `{owner_id}:{time_ns}:{lock_type}` where lock_type is `E` or `T`.
+
+use super::types::{LockToken, PathLockError, PathLockKind, PathLockResult};
+
+/// Encodes and decodes lock tokens in the `owner_id:time_ns:lock_type` text format.
+pub struct LockTokenCodec;
+
+impl LockTokenCodec {
+ /// Encode a `LockToken` into its wire format.
+ pub fn encode(token: &LockToken) -> String {
+ format!(
+ "{}:{}:{}",
+ token.owner_id,
+ token.time_ns,
+ token.lock_type.to_code()
+ )
+ }
+
+ /// Decode a raw token string into a `LockToken`.
+ /// Only accepts `E` (Exact) and `T` (Tree) lock type codes.
+ pub fn decode(raw: &str) -> PathLockResult<LockToken> {
+ let (owner_id, rest) = raw
+ .split_once(':')
+ .ok_or_else(|| PathLockError::InvalidToken(format!("missing ':' in token: {raw}")))?;
+
+ let (time_ns_str, rest) = rest.split_once(':').ok_or_else(|| {
+ PathLockError::InvalidToken(format!("missing second ':' in token: {raw}"))
+ })?;
+
+ let time_ns: u128 = time_ns_str.parse().map_err(|_| {
+ PathLockError::InvalidToken(format!("invalid time_ns in token: {raw}"))
+ })?;
+
+ let mut lock_type_chars = rest.chars();
+ let lock_type_char = lock_type_chars
+ .next()
+ .ok_or_else(|| PathLockError::InvalidToken(format!("empty lock type in token: {raw}")))?;
+ if lock_type_chars.next().is_some() {
+ return Err(PathLockError::InvalidToken(format!(
+ "invalid lock type in token: {raw}"
+ )));
+ }
+
+ let lock_type = PathLockKind::from_code(lock_type_char).ok_or_else(|| {
+ PathLockError::InvalidToken(format!(
+ "unknown lock type '{}' in token: {raw}",
+ lock_type_char
+ ))
+ })?;
+
+ Ok(LockToken {
+ owner_id: owner_id.to_string(),
+ time_ns,
+ lock_type,
+ })
+ }
+}
+
+#[cfg(test)]
+mod tests {
+ use super::*;
+
+ #[test]
+ fn roundtrip_supported_lock_types() {
+ for token in [
+ LockToken {
+ owner_id: "abc-123".to_string(),
+ time_ns: 1700000000000000000,
+ lock_type: PathLockKind::Exact,
+ },
+ LockToken {
+ owner_id: "xyz-456".to_string(),
+ time_ns: 42,
+ lock_type: PathLockKind::Tree,
+ },
+ ] {
+ let encoded = LockTokenCodec::encode(&token);
+ let decoded = LockTokenCodec::decode(&encoded).unwrap();
+ assert_eq!(decoded.owner_id, token.owner_id);
+ assert_eq!(decoded.time_ns, token.time_ns);
+ assert_eq!(decoded.lock_type, token.lock_type);
+ }
+ }
+
+ #[test]
+ fn rejects_legacy_and_malformed_tokens() {
+ for raw in [
+ "owner:100:P",
+ "owner:100:S",
+ "no-colons",
+ "a:b:c:d",
+ "owner:100:E:1",
+ "a:not-a-number:E",
+ ] {
+ assert!(matches!(
+ LockTokenCodec::decode(raw),
+ Err(PathLockError::InvalidToken(_))
+ ));
+ }
+ }
+}
diff --git a/crates/ragfs/src/lock/manager.rs b/crates/ragfs/src/lock/manager.rs
new file mode 100644
index 000000000..75da20ddb
--- /dev/null
+++ b/crates/ragfs/src/lock/manager.rs
@@ -0,0 +1,1885 @@
+//! PathLockManager — single source of truth for all lock semantics.
+//!
+//! Owns the provider, resolver, lease registry, and metrics. All lock acquisition,
+//! refresh, release, handoff, and adopt flows go through this manager.
+
+use std::collections::{HashMap, HashSet};
+use std::sync::Arc;
+use std::time::{Duration, Instant, SystemTime, UNIX_EPOCH};
+
+use tokio::sync::RwLock;
+use tracing::error;
+use uuid::Uuid;
+
+use crate::core::internal_names::{EXACT_LOCK_FILE_PREFIX, PATH_LOCK_FILE};
+use crate::core::{FileSystem, FsContextView};
+
+use super::metrics::LockMetrics;
+use super::provider::PathLockProvider;
+use super::resolver::{LockPathResolver, ResolvedExactPaths};
+use super::types::{
+ BorrowedPathLockLease, LockToken, OwnedPathLockLease, PathLockConflict, PathLockHandoffRef,
+ PathLockKind, PathLockLease, PathLockObserveSnapshot, PathLockRequest, PathLockResult,
+ PathLockError,
+};
+
+/// Configuration for the PathLockManager.
+#[derive(Debug, Clone)]
+pub struct PathLockConfig {
+ /// Built-in provider name: `filesystem` or `memory`.
+ pub provider: String,
+ /// Seconds after which a lock token is considered stale.
+ pub lock_expire_secs: f64,
+}
+
+impl Default for PathLockConfig {
+ fn default() -> Self {
+ Self {
+ provider: "filesystem".to_string(),
+ lock_expire_secs: 300.0,
+ }
+ }
+}
+
+/// Decision for one automatic PathLock operation under the current FS context.
+#[derive(Debug, Clone)]
+pub enum AutoPathLockAction {
+ /// The scoped context explicitly disables automatic PathLock.
+ Disabled,
+ /// An active owned lease already covers the operation.
+ Covered(OwnedPathLockLease),
+ /// No lease is supplied, so the caller must acquire locks.
+ Acquire,
+}
+
+/// Internal registry entry for an active lease.
+#[derive(Debug, Clone)]
+struct LeaseEntry {
+ lease: PathLockLease,
+ ownership_ref: String,
+ lock_kinds: HashMap<String, PathLockKind>,
+ last_active_at: Instant,
+}
+
+#[derive(Debug)]
+enum AcquisitionChange {
+ Created,
+ Reentrant,
+ Upgraded {
+ previous: LockToken,
+ replacement: LockToken,
+ },
+}
+
+/// Registry of all active leases in this process.
+#[derive(Debug, Default)]
+struct LeaseRegistry {
+ entries: HashMap<String, LeaseEntry>,
+ lock_refs: HashMap<(String, String), usize>,
+}
+
+impl LeaseRegistry {
+ /// Register one owned lease and increment its local token references.
+ fn insert(&mut self, lease: PathLockLease, ownership_ref: String) {
+ let lease_ref = lease.lease_ref.clone();
+ let lock_kinds = lease
+ .lock_paths
+ .iter()
+ .cloned()
+ .zip(lease.covered_paths.iter().map(|request| request.kind))
+ .collect();
+ let mut unique_paths = HashSet::new();
+ for lock_path in &lease.lock_paths {
+ if unique_paths.insert(lock_path.clone()) {
+ *self
+ .lock_refs
+ .entry((lease.owner_id.clone(), lock_path.clone()))
+ .or_default() += 1;
+ }
+ }
+ self.entries.insert(
+ lease_ref,
+ LeaseEntry {
+ lease,
+ ownership_ref,
+ lock_kinds,
+ last_active_at: Instant::now(),
+ },
+ );
+ }
+
+ /// Find one active lease for an owner.
+ fn get_by_owner(&self, owner_id: &str) -> Option<&LeaseEntry> {
+ self.entries
+ .values()
+ .find(|entry| entry.lease.owner_id == owner_id)
+ }
+
+ /// Find one active lease by its opaque reference.
+ fn get_by_ref(&self, lease_ref: &str) -> Option<&LeaseEntry> {
+ self.entries.get(lease_ref)
+ }
+
+ /// Remove one lease and return token paths whose local reference count reached zero.
+ fn remove(&mut self, lease_ref: &str) -> Option<(LeaseEntry, Vec<String>, Vec<String>)> {
+ let entry = self.entries.remove(lease_ref)?;
+ let release_paths = self.decrement_refs(&entry.lease.owner_id, &entry.lease.lock_paths);
+ let downgrade_paths = entry
+ .lock_kinds
+ .iter()
+ .filter(|(path, kind)| {
+ **kind == PathLockKind::Tree
+ && !release_paths.contains(path)
+ && self.strongest_kind(&entry.lease.owner_id, path) == Some(PathLockKind::Exact)
+ })
+ .map(|(path, _)| path.clone())
+ .collect();
+ Some((entry, release_paths, downgrade_paths))
+ }
+
+ /// Remove selected token references from one lease.
+ fn remove_selected(
+ &mut self,
+ lease_ref: &str,
+ selected_paths: &[String],
+ ) -> Option<(LeaseEntry, String, Vec<String>, Vec<String>)> {
+ let mut entry = self.entries.remove(lease_ref)?;
+ let original_entry = entry.clone();
+ let selected: HashSet<&str> = selected_paths.iter().map(String::as_str).collect();
+ let removed: Vec<String> = entry
+ .lease
+ .lock_paths
+ .iter()
+ .filter(|path| selected.contains(path.as_str()))
+ .cloned()
+ .collect();
+ entry
+ .lease
+ .lock_paths
+ .retain(|path| !selected.contains(path.as_str()));
+ entry
+ .lock_kinds
+ .retain(|path, _| !selected.contains(path.as_str()));
+ entry.lease.covered_paths = original_entry
+ .lease
+ .lock_paths
+ .iter()
+ .zip(&original_entry.lease.covered_paths)
+ .filter(|(path, _)| !selected.contains(path.as_str()))
+ .map(|(_, request)| request.clone())
+ .collect();
+
+ let owner_id = entry.lease.owner_id.clone();
+ let release_paths = self.decrement_refs(&owner_id, &removed);
+ if !entry.lease.lock_paths.is_empty() {
+ self.entries.insert(lease_ref.to_string(), entry);
+ }
+ let downgrade_paths = original_entry
+ .lock_kinds
+ .iter()
+ .filter(|(path, kind)| {
+ selected.contains(path.as_str())
+ && **kind == PathLockKind::Tree
+ && !release_paths.contains(path)
+ && self.strongest_kind(&owner_id, path) == Some(PathLockKind::Exact)
+ })
+ .map(|(path, _)| path.clone())
+ .collect();
+ Some((
+ original_entry,
+ owner_id,
+ release_paths,
+ downgrade_paths,
+ ))
+ }
+
+ /// Restore one lease after a provider release failure.
+ fn restore(&mut self, entry: LeaseEntry) {
+ self.entries
+ .insert(entry.lease.lease_ref.clone(), entry);
+ self.rebuild_lock_refs();
+ }
+
+ /// Rebuild local token reference counts from active lease entries.
+ fn rebuild_lock_refs(&mut self) {
+ let mut lock_refs = HashMap::new();
+ for entry in self.entries.values() {
+ let mut unique_paths = HashSet::new();
+ for lock_path in &entry.lease.lock_paths {
+ if unique_paths.insert(lock_path) {
+ *lock_refs
+ .entry((entry.lease.owner_id.clone(), lock_path.clone()))
+ .or_default() += 1;
+ }
+ }
+ }
+ self.lock_refs = lock_refs;
+ }
+
+ /// Update the last successful refresh timestamp for one lease.
+ fn touch(&mut self, lease_ref: &str) {
+ if let Some(entry) = self.entries.get_mut(lease_ref) {
+ entry.last_active_at = Instant::now();
+ }
+ }
+
+ /// Decrement local references and return paths no longer used by any local lease.
+ fn decrement_refs(&mut self, owner_id: &str, lock_paths: &[String]) -> Vec<String> {
+ let mut release_paths = Vec::new();
+ let mut unique_paths = HashSet::new();
+ for lock_path in lock_paths {
+ if !unique_paths.insert(lock_path.clone()) {
+ continue;
+ }
+ let key = (owner_id.to_string(), lock_path.clone());
+ match self.lock_refs.get_mut(&key) {
+ Some(count) if *count > 1 => *count -= 1,
+ Some(_) => {
+ self.lock_refs.remove(&key);
+ release_paths.push(lock_path.clone());
+ }
+ None => {}
+ }
+ }
+ release_paths
+ }
+
+ /// Return the strongest active reference kind for one owner and token path.
+ fn strongest_kind(&self, owner_id: &str, lock_path: &str) -> Option<PathLockKind> {
+ self.entries
+ .values()
+ .filter(|entry| entry.lease.owner_id == owner_id)
+ .filter_map(|entry| entry.lock_kinds.get(lock_path).copied())
+ .max_by_key(|kind| match kind {
+ PathLockKind::Exact => 0,
+ PathLockKind::Tree => 1,
+ })
+ }
+}
+
+/// The central lock manager.
+pub struct PathLockManager {
+ provider: Arc<dyn PathLockProvider>,
+ resolver: LockPathResolver,
+ lease_registry: Arc<RwLock<LeaseRegistry>>,
+ config: PathLockConfig,
+ metrics: Arc<RwLock<LockMetrics>>,
+}
+
+impl PathLockManager {
+ /// Create a new PathLockManager.
+ pub fn new(
+ fs: Arc<dyn FileSystem>,
+ provider: Arc<dyn PathLockProvider>,
+ config: PathLockConfig,
+ ) -> Self {
+ let registry = Arc::new(RwLock::new(LeaseRegistry::default()));
+ let metrics = Arc::new(RwLock::new(LockMetrics::default()));
+
+ // Spawn a background task that refreshes active owned leases.
+ let refresh_registry = registry.clone();
+ let refresh_provider = provider.clone();
+ let refresh_config = config.clone();
+ let refresh_metrics = metrics.clone();
+ let refresh_interval = Duration::from_secs_f64(config.lock_expire_secs / 3.0);
+ tokio::spawn(async move {
+ loop {
+ tokio::time::sleep(refresh_interval).await;
+ let now_ns = Self::now_ns();
+ let lease_refs: Vec<String> = {
+ let reg = refresh_registry.read().await;
+ reg.entries
+ .iter()
+ .map(|(lease_ref, _)| lease_ref.clone())
+ .collect()
+ };
+ for lease_ref in lease_refs {
+ let refresh_guard = refresh_registry.read().await;
+ let Some(entry) = refresh_guard.entries.get(&lease_ref) else {
+ continue;
+ };
+ let owner_id = entry.lease.owner_id.clone();
+ let lock_paths = entry.lease.lock_paths.clone();
+ let mut all_ok = true;
+ for lp in &lock_paths {
+ match refresh_provider.refresh_token(lp, &owner_id, now_ns).await {
+ Ok(true) => {}
+ _ => all_ok = false,
+ }
+ }
+ drop(refresh_guard);
+ if all_ok {
+ refresh_registry.write().await.touch(&lease_ref);
+ }
+ }
+ let stale_cutoff = Instant::now()
+ - Duration::from_secs_f64(refresh_config.lock_expire_secs * 2.0);
+ let stale_refs: Vec<String> = {
+ let reg = refresh_registry.read().await;
+ reg.entries
+ .iter()
+ .filter(|(_, entry)| entry.last_active_at <= stale_cutoff)
+ .map(|(lease_ref, _)| lease_ref.clone())
+ .collect()
+ };
+ let mut removed = 0;
+ for lease_ref in stale_refs {
+ let removed_entry = refresh_registry.write().await.remove(&lease_ref);
+ if let Some((entry, release_paths, _)) = removed_entry {
+ for lock_path in release_paths {
+ let _ = refresh_provider
+ .remove_token(&lock_path, &entry.lease.owner_id)
+ .await;
+ }
+ removed += 1;
+ }
+ }
+ let active_count = refresh_registry.read().await.entries.len();
+ let mut m = refresh_metrics.write().await;
+ m.active_lock_count = active_count;
+ m.stale_leases_released += removed;
+ }
+ });
+
+ Self {
+ resolver: LockPathResolver::new(fs),
+ provider,
+ lease_registry: registry,
+ config,
+ metrics,
+ }
+ }
+
+ /// Build one release error when the provider reports the token changed underneath us.
+ fn release_changed_error(lock_path: &str) -> PathLockError {
+ PathLockError::Io(format!("lock path '{lock_path}' changed while releasing"))
+ }
+
+ /// Current nanosecond timestamp.
+ fn now_ns() -> u128 {
+ SystemTime::now()
+ .duration_since(UNIX_EPOCH)
+ .unwrap_or_default()
+ .as_nanos()
+ }
+
+ /// Generate a new UUIDv4 owner_id.
+ fn new_owner_id() -> String {
+ Uuid::new_v4().to_string()
+ }
+
+ /// Normalize, deduplicate, and sort requests with Tree taking precedence over Exact.
+ fn normalize_requests(requests: &[PathLockRequest]) -> Vec<PathLockRequest> {
+ let mut by_path: HashMap<String, PathLockKind> = HashMap::new();
+ for request in requests {
+ let trimmed = request.path.trim_end_matches('/');
+ let path = if trimmed.is_empty() {
+ "/".to_string()
+ } else {
+ trimmed.to_string()
+ };
+ by_path
+ .entry(path)
+ .and_modify(|kind| {
+ if request.kind == PathLockKind::Tree {
+ *kind = PathLockKind::Tree;
+ }
+ })
+ .or_insert(request.kind);
+ }
+
+ let mut normalized: Vec<PathLockRequest> = by_path
+ .into_iter()
+ .map(|(path, kind)| PathLockRequest { path, kind })
+ .collect();
+ normalized.sort_by(|a, b| {
+ a.path
+ .len()
+ .cmp(&b.path.len())
+ .then_with(|| a.path.cmp(&b.path))
+ });
+ normalized
+ }
+
+ /// Check if a token is stale based on config.
+ fn is_stale(&self, token: &LockToken, now_ns: u128) -> bool {
+ let expire_ns = (self.config.lock_expire_secs * 1_000_000_000.0) as u128;
+ now_ns.saturating_sub(token.time_ns) > expire_ns
+ }
+
+ /// Resolve a trusted reentrant owner from an active local lease capability.
+ async fn resolve_owner_id(
+ &self,
+ owner_capability: Option<(&str, &str)>,
+ ) -> PathLockResult<String> {
+ match owner_capability {
+ Some((lease_ref, ownership_ref)) => self
+ .get_owned_lease_by_capability(lease_ref, ownership_ref)
+ .await
+ .map(|lease| lease.lease.owner_id)
+ .ok_or_else(|| {
+ PathLockError::InvalidRequest(format!(
+ "owned lease capability does not match ref '{lease_ref}'"
+ ))
+ }),
+ None => Ok(Self::new_owner_id()),
+ }
+ }
+
+ // ── Public API ──
+
+ /// Acquire an exact lock on a single path.
+ pub async fn acquire_exact(
+ &self,
+ path: &str,
+ timeout: Duration,
+ owner_capability: Option<(&str, &str)>,
+ ) -> PathLockResult<OwnedPathLockLease> {
+ let request = PathLockRequest {
+ path: path.to_string(),
+ kind: PathLockKind::Exact,
+ };
+ self.acquire_batch(&[request], timeout, owner_capability)
+ .await
+ }
+
+ /// Acquire a tree lock on a single path.
+ pub async fn acquire_tree(
+ &self,
+ path: &str,
+ timeout: Duration,
+ owner_capability: Option<(&str, &str)>,
+ ) -> PathLockResult<OwnedPathLockLease> {
+ let request = PathLockRequest {
+ path: path.to_string(),
+ kind: PathLockKind::Tree,
+ };
+ self.acquire_batch(&[request], timeout, owner_capability)
+ .await
+ }
+
+ /// Acquire exact locks on multiple paths.
+ pub async fn acquire_exact_batch(
+ &self,
+ paths: &[String],
+ timeout: Duration,
+ owner_capability: Option<(&str, &str)>,
+ ) -> PathLockResult<OwnedPathLockLease> {
+ let requests: Vec<PathLockRequest> = paths
+ .iter()
+ .map(|p| PathLockRequest {
+ path: p.clone(),
+ kind: PathLockKind::Exact,
+ })
+ .collect();
+ self.acquire_batch(&requests, timeout, owner_capability)
+ .await
+ }
+
+ /// Acquire tree locks on multiple paths.
+ pub async fn acquire_tree_batch(
+ &self,
+ paths: &[String],
+ timeout: Duration,
+ owner_capability: Option<(&str, &str)>,
+ ) -> PathLockResult<OwnedPathLockLease> {
+ let requests: Vec<PathLockRequest> = paths
+ .iter()
+ .map(|p| PathLockRequest {
+ path: p.clone(),
+ kind: PathLockKind::Tree,
+ })
+ .collect();
+ self.acquire_batch(&requests, timeout, owner_capability)
+ .await
+ }
+
+ /// Acquire a mixed batch of exact and tree locks.
+ pub async fn acquire_exact_tree_batch(
+ &self,
+ exact_paths: &[String],
+ tree_paths: &[String],
+ timeout: Duration,
+ owner_capability: Option<(&str, &str)>,
+ ) -> PathLockResult<OwnedPathLockLease> {
+ let mut requests: Vec<PathLockRequest> = exact_paths
+ .iter()
+ .map(|p| PathLockRequest {
+ path: p.clone(),
+ kind: PathLockKind::Exact,
+ })
+ .collect();
+ requests.extend(tree_paths.iter().map(|p| PathLockRequest {
+ path: p.clone(),
+ kind: PathLockKind::Tree,
+ }));
+ self.acquire_batch(&requests, timeout, owner_capability)
+ .await
+ }
+
+ /// Acquire a batch of locks with all-or-nothing semantics.
+ ///
+ /// Requests are sorted deterministically by `(len(path), path)` to avoid deadlocks.
+ pub async fn acquire_batch(
+ &self,
+ requests: &[PathLockRequest],
+ timeout: Duration,
+ owner_capability: Option<(&str, &str)>,
+ ) -> PathLockResult<OwnedPathLockLease> {
+ if requests.is_empty() {
+ return Err(PathLockError::InvalidRequest(
+ "lock request batch must not be empty".to_string(),
+ ));
+ }
+ let sorted = Self::normalize_requests(requests);
+
+ let owner_id = self.resolve_owner_id(owner_capability).await?;
+
+ let start = Instant::now();
+ let mut acquired_lock_paths: Vec<(String, AcquisitionChange)> = Vec::new();
+ let mut is_waiting = false;
+
+ loop {
+ let mut conflict: Option<PathLockError> = None;
+ let mut exact_resolutions: HashMap<String, ResolvedExactPaths> = HashMap::new();
+
+ for req in &sorted {
+ match req.kind {
+ PathLockKind::Exact => {
+ // Check ancestor tree locks — a tree lock on an ancestor
+ // blocks any exact lock on a descendant.
+ if let Err(e) = self.check_ancestor_tree_locks(&req.path, &owner_id).await {
+ conflict = Some(e);
+ break;
+ }
+ let resolved = self
+ .resolver
+ .resolve_exact_paths(&req.path)
+ .await?;
+ if let Err(e) = self
+ .check_lock_paths(&resolved.conflict_paths, &owner_id)
+ .await
+ {
+ conflict = Some(e);
+ break;
+ }
+ let lock_path = resolved.acquire_lock_path.clone();
+ exact_resolutions.insert(req.path.clone(), resolved);
+ if let Err(e) = self.ensure_lock_dir(&lock_path).await {
+ conflict = Some(PathLockError::Io(format!(
+ "failed to create lock dir: {e}"
+ )));
+ break;
+ }
+ match self
+ .try_acquire_one(&lock_path, &owner_id, PathLockKind::Exact)
+ .await
+ {
+ Ok(change) => acquired_lock_paths.push((lock_path, change)),
+ Err(e) => {
+ conflict = Some(e);
+ break;
+ }
+ }
+ }
+ PathLockKind::Tree => {
+ let lock_path = self.resolver.resolve_tree_lock_path(&req.path).await?;
+ // Check conflicts before creating directories so
+ // failed requests don't leave empty dirs behind.
+ if let Err(e) = self.check_ancestor_tree_locks(&req.path, &owner_id).await {
+ conflict = Some(e);
+ break;
+ }
+ let exact_candidates = self
+ .resolver
+ .resolve_exact_conflict_paths(&req.path)
+ .await?;
+ if let Err(e) =
+ self.check_lock_paths(&exact_candidates, &owner_id).await
+ {
+ conflict = Some(e);
+ break;
+ }
+ if let Err(e) = self.check_descendant_locks(&req.path, &owner_id).await {
+ conflict = Some(e);
+ break;
+ }
+ if let Err(e) = self.ensure_lock_dir(&lock_path).await {
+ conflict = Some(PathLockError::Io(format!(
+ "failed to create lock dir: {e}"
+ )));
+ break;
+ }
+ match self
+ .try_acquire_one(&lock_path, &owner_id, PathLockKind::Tree)
+ .await
+ {
+ Ok(change) => acquired_lock_paths.push((lock_path, change)),
+ Err(e) => {
+ conflict = Some(e);
+ break;
+ }
+ }
+ }
+ }
+ if conflict.is_some() {
+ break;
+ }
+ }
+
+ if let Some(err) = conflict {
+ // Rollback all acquired locks.
+ self.rollback_acquisitions(&acquired_lock_paths, &owner_id)
+ .await?;
+ acquired_lock_paths.clear();
+
+ if !matches!(err, PathLockError::Conflict { .. }) {
+ if is_waiting {
+ let mut metrics = self.metrics.write().await;
+ metrics.waiting_lock_count = metrics.waiting_lock_count.saturating_sub(1);
+ }
+ return Err(err);
+ }
+
+ // Track conflict and waiting metrics.
+ {
+ let mut metrics = self.metrics.write().await;
+ if !is_waiting {
+ is_waiting = true;
+ metrics.waiting_lock_count += 1;
+ }
+ if let PathLockError::Conflict {
+ ref lock_path,
+ ref owner,
+ kind,
+ } = &err
+ {
+ metrics.record_conflict(PathLockConflict {
+ lock_path: lock_path.clone(),
+ conflicting_owner: owner.clone(),
+ conflicting_kind: *kind,
+ });
+ }
+ }
+
+ // Check timeout.
+ if start.elapsed() >= timeout {
+ if is_waiting {
+ let mut m = self.metrics.write().await;
+ m.waiting_lock_count = m.waiting_lock_count.saturating_sub(1);
+ }
+ return Err(PathLockError::Timeout {
+ elapsed_ms: start.elapsed().as_millis() as u64,
+ });
+ }
+
+ // Try stale cleanup on the conflicting lock, then retry.
+ if let PathLockError::Conflict { ref lock_path, .. } = &err {
+ if let Some(token) = self.provider.read_token(lock_path).await? {
+ let now_ns = Self::now_ns();
+ if self.is_stale(&token, now_ns) {
+ if self
+ .provider
+ .remove_token(lock_path, &token.owner_id)
+ .await?
+ {
+ self.metrics.write().await.stale_tokens_removed += 1;
+ }
+ }
+ }
+ }
+
+ tokio::time::sleep(Duration::from_millis(50)).await;
+ continue;
+ }
+
+ // Post-conflict check: after writing all tokens, re-verify no
+ // conflicting lock appeared in the TOCTOU window between pre-check
+ // and token write.
+ let mut post_conflict: Option<PathLockError> = None;
+ for req in &sorted {
+ match req.kind {
+ PathLockKind::Exact => {
+ if let Err(e) =
+ self.check_ancestor_tree_locks(&req.path, &owner_id).await
+ {
+ post_conflict = Some(e);
+ break;
+ }
+ let resolved = exact_resolutions.get(&req.path).ok_or_else(|| {
+ PathLockError::Io(format!(
+ "missing cached exact resolution for '{}'",
+ req.path
+ ))
+ })?;
+ if let Err(e) = self
+ .check_lock_paths(&resolved.conflict_paths, &owner_id)
+ .await
+ {
+ post_conflict = Some(e);
+ break;
+ }
+ }
+ PathLockKind::Tree => {
+ if let Err(e) =
+ self.check_ancestor_tree_locks(&req.path, &owner_id).await
+ {
+ post_conflict = Some(e);
+ break;
+ }
+ let exact_candidates = self
+ .resolver
+ .resolve_exact_conflict_paths(&req.path)
+ .await?;
+ if let Err(e) =
+ self.check_lock_paths(&exact_candidates, &owner_id).await
+ {
+ post_conflict = Some(e);
+ break;
+ }
+ if let Err(e) =
+ self.check_descendant_locks(&req.path, &owner_id).await
+ {
+ post_conflict = Some(e);
+ break;
+ }
+ }
+ }
+ }
+
+ if let Some(err) = post_conflict {
+ // Another process slipped in — rollback and retry.
+ self.rollback_acquisitions(&acquired_lock_paths, &owner_id)
+ .await?;
+ acquired_lock_paths.clear();
+
+ if !matches!(err, PathLockError::Conflict { .. }) {
+ if is_waiting {
+ let mut metrics = self.metrics.write().await;
+ metrics.waiting_lock_count = metrics.waiting_lock_count.saturating_sub(1);
+ }
+ return Err(err);
+ }
+
+ {
+ let mut metrics = self.metrics.write().await;
+ if !is_waiting {
+ is_waiting = true;
+ metrics.waiting_lock_count += 1;
+ }
+ if let PathLockError::Conflict {
+ ref lock_path,
+ ref owner,
+ kind,
+ } = &err
+ {
+ metrics.record_conflict(PathLockConflict {
+ lock_path: lock_path.clone(),
+ conflicting_owner: owner.clone(),
+ conflicting_kind: *kind,
+ });
+ }
+ }
+
+ if start.elapsed() >= timeout {
+ if is_waiting {
+ let mut m = self.metrics.write().await;
+ m.waiting_lock_count = m.waiting_lock_count.saturating_sub(1);
+ }
+ return Err(PathLockError::Timeout {
+ elapsed_ms: start.elapsed().as_millis() as u64,
+ });
+ }
+
+ tokio::time::sleep(Duration::from_millis(50)).await;
+ continue;
+ }
+
+ // All acquired and post-verified successfully.
+ let lease = PathLockLease {
+ lease_ref: Self::new_owner_id(),
+ owner_id: owner_id.clone(),
+ lock_paths: acquired_lock_paths
+ .into_iter()
+ .map(|(lock_path, _)| lock_path)
+ .collect(),
+ covered_paths: sorted.clone(),
+ };
+ let ownership_ref = Self::new_owner_id();
+ self.lease_registry
+ .write()
+ .await
+ .insert(lease.clone(), ownership_ref.clone());
+
+ let active_count = self.lease_registry.read().await.entries.len();
+ let mut metrics = self.metrics.write().await;
+ metrics.active_lock_count = active_count;
+ metrics.wait_duration_ms += start.elapsed().as_millis() as u64;
+ if is_waiting {
+ metrics.waiting_lock_count = metrics.waiting_lock_count.saturating_sub(1);
+ }
+
+ return Ok(OwnedPathLockLease {
+ lease,
+ ownership_ref,
+ });
+ }
+ }
+
+ /// Roll back token changes made by one incomplete batch acquisition.
+ async fn rollback_acquisitions(
+ &self,
+ acquired_lock_paths: &[(String, AcquisitionChange)],
+ owner_id: &str,
+ ) -> PathLockResult<()> {
+ for (lock_path, change) in acquired_lock_paths.iter().rev() {
+ match change {
+ AcquisitionChange::Created => {
+ self.provider.remove_token(lock_path, owner_id).await?;
+ }
+ AcquisitionChange::Reentrant => {}
+ AcquisitionChange::Upgraded {
+ previous,
+ replacement,
+ } => {
+ if !self
+ .provider
+ .compare_and_write_token(lock_path, replacement, previous)
+ .await?
+ {
+ return Err(PathLockError::Io(format!(
+ "failed to roll back token upgrade at '{lock_path}'"
+ )));
+ }
+ }
+ }
+ }
+ Ok(())
+ }
+
+ /// Try to acquire a single lock path.
+ async fn try_acquire_one(
+ &self,
+ lock_path: &str,
+ owner_id: &str,
+ kind: PathLockKind,
+ ) -> PathLockResult<AcquisitionChange> {
+ let now_ns = Self::now_ns();
+ let token = LockToken {
+ owner_id: owner_id.to_string(),
+ time_ns: now_ns,
+ lock_type: kind,
+ };
+
+ // Check existing token.
+ if let Some(existing) = self.provider.read_token(lock_path).await? {
+ if existing.owner_id == owner_id {
+ if existing.lock_type == PathLockKind::Exact && kind == PathLockKind::Tree {
+ if self
+ .provider
+ .compare_and_write_token(lock_path, &existing, &token)
+ .await?
+ {
+ return Ok(AcquisitionChange::Upgraded {
+ previous: existing,
+ replacement: token,
+ });
+ }
+ return Err(PathLockError::Conflict {
+ lock_path: lock_path.to_string(),
+ owner: owner_id.to_string(),
+ kind: existing.lock_type,
+ });
+ }
+ return Ok(AcquisitionChange::Reentrant);
+ }
+ if !self.is_stale(&existing, now_ns) {
+ return Err(PathLockError::Conflict {
+ lock_path: lock_path.to_string(),
+ owner: existing.owner_id,
+ kind: existing.lock_type,
+ });
+ }
+ // Stale — remove it.
+ let _ = self.provider.remove_token(lock_path, &existing.owner_id).await;
+ }
+
+ self.provider.try_create_token(lock_path, &token).await?;
+ Ok(AcquisitionChange::Created)
+ }
+
+ /// Check concrete lock-file paths for a live token owned by another owner.
+ async fn check_lock_paths(
+ &self,
+ lock_paths: &[String],
+ owner_id: &str,
+ ) -> PathLockResult<()> {
+ let now_ns = Self::now_ns();
+ for lock_path in lock_paths {
+ if let Some(token) = self.provider.read_token(lock_path).await? {
+ if token.owner_id != owner_id && !self.is_stale(&token, now_ns) {
+ return Err(PathLockError::Conflict {
+ lock_path: lock_path.clone(),
+ owner: token.owner_id,
+ kind: token.lock_type,
+ });
+ }
+ }
+ }
+ Ok(())
+ }
+
+ /// Check ancestor directories for tree locks that would conflict.
+ async fn check_ancestor_tree_locks(
+ &self,
+ path: &str,
+ owner_id: &str,
+ ) -> PathLockResult<()> {
+ let mut current = path.to_string();
+ let now_ns = Self::now_ns();
+
+ loop {
+ let parent = match current.rsplit_once('/') {
+ Some((p, _)) if !p.is_empty() => p.to_string(),
+ Some(_) if current != "/" => "/".to_string(),
+ _ => break,
+ };
+
+ let ancestor_lock = if parent == "/" {
+ format!("/{}", PATH_LOCK_FILE)
+ } else {
+ format!("{}/{}", parent, PATH_LOCK_FILE)
+ };
+ if let Some(token) = self.provider.read_token(&ancestor_lock).await? {
+ // Only Tree locks propagate to descendants; an Exact lock on
+ // /a must not block /a/b.
+ if token.lock_type == PathLockKind::Tree
+ && token.owner_id != owner_id
+ && !self.is_stale(&token, now_ns)
+ {
+ return Err(PathLockError::Conflict {
+ lock_path: ancestor_lock,
+ owner: token.owner_id,
+ kind: token.lock_type,
+ });
+ }
+ }
+
+ current = parent;
+ }
+ Ok(())
+ }
+
+ /// Check for descendant locks that would conflict with a tree lock.
+ async fn check_descendant_locks(
+ &self,
+ path: &str,
+ owner_id: &str,
+ ) -> PathLockResult<()> {
+ let scan_start = Instant::now();
+ let descendants = self.provider.scan_descendant_locks(path).await?;
+ let now_ns = Self::now_ns();
+
+ let mut metrics = self.metrics.write().await;
+ metrics.descendant_scan_count += 1;
+ metrics.descendant_scan_duration_ms += scan_start.elapsed().as_millis() as u64;
+ drop(metrics);
+
+ for lp in descendants {
+ if let Some(token) = self.provider.read_token(&lp).await? {
+ if token.owner_id != owner_id && !self.is_stale(&token, now_ns) {
+ return Err(PathLockError::Conflict {
+ lock_path: lp,
+ owner: token.owner_id,
+ kind: token.lock_type,
+ });
+ }
+ }
+ }
+ Ok(())
+ }
+
+ /// Ensure the parent directory of a lock path exists.
+ async fn ensure_lock_dir(&self, lock_path: &str) -> PathLockResult<()> {
+ if let Some(parent_end) = lock_path.rfind('/') {
+ let parent = &lock_path[..parent_end];
+ if parent.is_empty() || parent == "/" {
+ return Ok(());
+ }
+ // Walk up creating missing ancestors.
+ let mut missing: Vec<String> = Vec::new();
+ let mut current = parent.to_string();
+ loop {
+ match self.resolver.fs.stat(&current).await {
+ Ok(info) if info.is_dir => break,
+ _ => {
+ missing.push(current.clone());
+ match current.rsplit_once('/') {
+ Some((p, _)) if !p.is_empty() => current = p.to_string(),
+ _ => break,
+ }
+ }
+ }
+ }
+ for dir in missing.into_iter().rev() {
+ self.resolver.fs.mkdir(&dir, 0o755).await.map_err(|e| {
+ PathLockError::Io(format!("failed to create lock dir '{dir}': {e}"))
+ })?;
+ }
+ }
+ Ok(())
+ }
+
+ /// Refresh an owned lease. Returns "refreshed", "lost", or "failed".
+ pub async fn refresh(&self, lease: &OwnedPathLockLease) -> PathLockResult<String> {
+ let now_ns = Self::now_ns();
+ let mut all_ok = true;
+ let mut any_ok = false;
+
+ for lp in &lease.lease.lock_paths {
+ match self
+ .provider
+ .refresh_token(lp, &lease.lease.owner_id, now_ns)
+ .await
+ {
+ Ok(true) => any_ok = true,
+ Ok(false) => all_ok = false,
+ Err(_) => all_ok = false,
+ }
+ }
+
+ if any_ok {
+ self.lease_registry
+ .write()
+ .await
+ .touch(&lease.lease.lease_ref);
+ }
+
+ if all_ok && any_ok {
+ Ok("refreshed".to_string())
+ } else if any_ok {
+ Ok("lost".to_string())
+ } else {
+ Ok("failed".to_string())
+ }
+ }
+
+ /// Release an owned lease.
+ pub async fn release(&self, lease: &OwnedPathLockLease) -> PathLockResult<()> {
+ let removed = self
+ .lease_registry
+ .write()
+ .await
+ .remove(&lease.lease.lease_ref);
+ if let Some((mut entry, release_paths, downgrade_paths)) = removed {
+ let mut failed_paths = Vec::new();
+ let mut first_error = None;
+ for lock_path in release_paths {
+ match self
+ .provider
+ .remove_token(&lock_path, &entry.lease.owner_id)
+ .await
+ {
+ Ok(true) => {}
+ Ok(false) => {
+ failed_paths.push(lock_path.clone());
+ if first_error.is_none() {
+ first_error = Some(Self::release_changed_error(&lock_path));
+ }
+ }
+ Err(error) => {
+ failed_paths.push(lock_path);
+ if first_error.is_none() {
+ first_error = Some(error);
+ }
+ }
+ }
+ }
+ for lock_path in downgrade_paths {
+ if let Err(error) = self
+ .downgrade_token_to_exact(&lock_path, &entry.lease.owner_id)
+ .await
+ {
+ failed_paths.push(lock_path);
+ if first_error.is_none() {
+ first_error = Some(error);
+ }
+ }
+ }
+ if let Some(error) = first_error {
+ let failed: HashSet<&str> = failed_paths.iter().map(String::as_str).collect();
+ entry.lease.covered_paths = entry
+ .lease
+ .lock_paths
+ .iter()
+ .zip(&entry.lease.covered_paths)
+ .filter(|(path, _)| failed.contains(path.as_str()))
+ .map(|(_, request)| request.clone())
+ .collect();
+ entry.lease.lock_paths = failed_paths;
+ entry
+ .lock_kinds
+ .retain(|path, _| entry.lease.lock_paths.contains(path));
+ error!(
+ lease_ref = %entry.lease.lease_ref,
+ owner_id = %entry.lease.owner_id,
+ lock_paths = ?entry.lease.lock_paths,
+ error = %error,
+ "failed to release pathlock lease"
+ );
+ self.lease_registry.write().await.restore(entry);
+ return Err(error);
+ }
+ }
+ let active_count = self.lease_registry.read().await.entries.len();
+ let mut metrics = self.metrics.write().await;
+ metrics.active_lock_count = active_count;
+ Ok(())
+ }
+
+ /// Release selected lock paths from an owned lease.
+ pub async fn release_selected(
+ &self,
+ lease: &OwnedPathLockLease,
+ lock_paths: &[String],
+ ) -> PathLockResult<()> {
+ let removed = self
+ .lease_registry
+ .write()
+ .await
+ .remove_selected(&lease.lease.lease_ref, lock_paths);
+ if let Some((mut entry, owner_id, release_paths, downgrade_paths)) = removed {
+ let mut failed_paths = Vec::new();
+ let mut first_error = None;
+ for lock_path in release_paths {
+ match self.provider.remove_token(&lock_path, &owner_id).await {
+ Ok(true) => {}
+ Ok(false) => {
+ failed_paths.push(lock_path.clone());
+ if first_error.is_none() {
+ first_error = Some(Self::release_changed_error(&lock_path));
+ }
+ }
+ Err(error) => {
+ failed_paths.push(lock_path);
+ if first_error.is_none() {
+ first_error = Some(error);
+ }
+ }
+ }
+ }
+ for lock_path in downgrade_paths {
+ if let Err(error) = self.downgrade_token_to_exact(&lock_path, &owner_id).await {
+ failed_paths.push(lock_path);
+ if first_error.is_none() {
+ first_error = Some(error);
+ }
+ }
+ }
+ if let Some(error) = first_error {
+ let selected: HashSet<&str> = lock_paths.iter().map(String::as_str).collect();
+ let failed: HashSet<&str> = failed_paths.iter().map(String::as_str).collect();
+ let retained: Vec<(String, PathLockRequest)> = entry
+ .lease
+ .lock_paths
+ .iter()
+ .zip(&entry.lease.covered_paths)
+ .filter(|(path, _)| {
+ !selected.contains(path.as_str()) || failed.contains(path.as_str())
+ })
+ .map(|(path, request)| (path.clone(), request.clone()))
+ .collect();
+ entry.lease.lock_paths =
+ retained.iter().map(|(path, _)| path.clone()).collect();
+ entry.lease.covered_paths =
+ retained.into_iter().map(|(_, request)| request).collect();
+ entry
+ .lock_kinds
+ .retain(|path, _| entry.lease.lock_paths.contains(path));
+ self.lease_registry.write().await.restore(entry);
+ return Err(error);
+ }
+ }
+ let active_count = self.lease_registry.read().await.entries.len();
+ self.metrics.write().await.active_lock_count = active_count;
+ Ok(())
+ }
+
+ /// Atomically reduce one same-owner Tree token to Exact.
+ async fn downgrade_token_to_exact(
+ &self,
+ lock_path: &str,
+ owner_id: &str,
+ ) -> PathLockResult<()> {
+ loop {
+ let Some(current) = self.provider.read_token(lock_path).await? else {
+ return Ok(());
+ };
+ if current.owner_id != owner_id {
+ return Err(PathLockError::Conflict {
+ lock_path: lock_path.to_string(),
+ owner: current.owner_id,
+ kind: current.lock_type,
+ });
+ }
+ if current.lock_type == PathLockKind::Exact {
+ return Ok(());
+ }
+ let replacement = LockToken {
+ owner_id: current.owner_id.clone(),
+ time_ns: current.time_ns,
+ lock_type: PathLockKind::Exact,
+ };
+ if self
+ .provider
+ .compare_and_write_token(lock_path, &current, &replacement)
+ .await?
+ {
+ return Ok(());
+ }
+ }
+ }
+
+ /// Create a borrowed view of an owned lease.
+ pub fn as_borrowed(&self, lease: &OwnedPathLockLease) -> BorrowedPathLockLease {
+ BorrowedPathLockLease {
+ lease: lease.lease.clone(),
+ }
+ }
+
+ /// Export a handoff ref from an owned lease.
+ pub fn to_handoff(&self, lease: &OwnedPathLockLease) -> PathLockHandoffRef {
+ PathLockHandoffRef {
+ owner_id: lease.lease.owner_id.clone(),
+ lock_paths: lease.lease.lock_paths.clone(),
+ covered_paths: lease.lease.covered_paths.clone(),
+ }
+ }
+
+ /// Mark an owned lease as handed off (local lifecycle ends).
+ pub async fn handoff(&self, lease: &OwnedPathLockLease) -> PathLockResult<()> {
+ self.lease_registry
+ .write()
+ .await
+ .remove(&lease.lease.lease_ref);
+ let active_count = self.lease_registry.read().await.entries.len();
+ self.metrics.write().await.active_lock_count = active_count;
+ Ok(())
+ }
+
+ /// Adopt a handoff ref, returning a new owned lease.
+ pub async fn adopt(
+ &self,
+ handoff: &PathLockHandoffRef,
+ ) -> PathLockResult<OwnedPathLockLease> {
+ if handoff.owner_id.is_empty() || handoff.lock_paths.is_empty() {
+ return Err(PathLockError::InvalidRequest(
+ "handoff owner_id and lock_paths must not be empty".to_string(),
+ ));
+ }
+ let legacy_handoff = handoff.covered_paths.is_empty();
+ if !legacy_handoff && handoff.covered_paths.len() != handoff.lock_paths.len() {
+ return Err(PathLockError::InvalidRequest(
+ "handoff lock_paths and covered_paths must have equal lengths".to_string(),
+ ));
+ }
+ let now_ns = Self::now_ns();
+
+ // ponytail: legacy durable handoffs only persisted owner_id/handle_id + lock_paths.
+ // We validate live ownership/kind by the lock file path itself and keep covered_paths empty.
+ // Upgrade path: once old queue payloads are drained, remove this branch and require covered_paths.
+ for (index, lp) in handoff.lock_paths.iter().enumerate() {
+ let expected_kind = if legacy_handoff {
+ let file_name = lp.rsplit('/').next().unwrap_or("");
+ if lp == &format!("/{}", PATH_LOCK_FILE) || lp.ends_with(&format!("/{}", PATH_LOCK_FILE)) {
+ PathLockKind::Tree
+ } else if file_name.starts_with(EXACT_LOCK_FILE_PREFIX) {
+ PathLockKind::Exact
+ } else {
+ return Err(PathLockError::InvalidRequest(format!(
+ "legacy handoff lock path '{lp}' is not a supported lock file"
+ )));
+ }
+ } else {
+ let request = &handoff.covered_paths[index];
+ let expected_paths = match request.kind {
+ PathLockKind::Exact => {
+ self.resolver.resolve_exact_conflict_paths(&request.path).await?
+ }
+ PathLockKind::Tree => {
+ vec![self.resolver.resolve_tree_lock_path(&request.path).await?]
+ }
+ };
+ if !expected_paths.contains(lp) {
+ return Err(PathLockError::InvalidRequest(format!(
+ "handoff coverage '{}' does not map to lock path '{lp}'",
+ request.path
+ )));
+ }
+ request.kind
+ };
+ match self.provider.read_token(lp).await? {
+ Some(token)
+ if token.owner_id == handoff.owner_id && token.lock_type == expected_kind =>
+ {
+ // Still valid — refresh the timestamp.
+ match self
+ .provider
+ .refresh_token(lp, &handoff.owner_id, now_ns)
+ .await
+ {
+ Ok(true) => {}
+ Ok(false) => {
+ return Err(PathLockError::HandoffFailed(format!(
+ "lock path '{lp}' changed while adopting owner '{}'",
+ handoff.owner_id
+ )));
+ }
+ Err(error) => return Err(error),
+ }
+ }
+ _ => {
+ return Err(PathLockError::HandoffFailed(format!(
+ "lock path '{lp}' is no longer owned by '{}'",
+ handoff.owner_id
+ )));
+ }
+ }
+ }
+
+ let lease = PathLockLease {
+ lease_ref: Self::new_owner_id(),
+ owner_id: handoff.owner_id.clone(),
+ lock_paths: handoff.lock_paths.clone(),
+ covered_paths: handoff.covered_paths.clone(),
+ };
+ let ownership_ref = Self::new_owner_id();
+ self.lease_registry
+ .write()
+ .await
+ .insert(lease.clone(), ownership_ref.clone());
+
+ let active_count = self.lease_registry.read().await.entries.len();
+ self.metrics.write().await.active_lock_count = active_count;
+
+ Ok(OwnedPathLockLease {
+ lease,
+ ownership_ref,
+ })
+ }
+
+ /// Check if a path is locked (for observability).
+ pub async fn is_locked(&self, path: &str, ignore_stale: bool) -> PathLockResult<bool> {
+ let now_ns = Self::now_ns();
+
+ // Check own .path.ovlock.
+ let dir_lock = format!("{}/{}", path.trim_end_matches('/'), PATH_LOCK_FILE);
+ if let Ok(Some(token)) = self.provider.read_token(&dir_lock).await {
+ if !ignore_stale || !self.is_stale(&token, now_ns) {
+ return Ok(true);
+ }
+ }
+
+ // Check exact sidecar.
+ let exact_paths = self.resolver.resolve_exact_conflict_paths(path).await?;
+ for lp in &exact_paths {
+ if let Ok(Some(token)) = self.provider.read_token(lp).await {
+ if !ignore_stale || !self.is_stale(&token, now_ns) {
+ return Ok(true);
+ }
+ }
+ }
+
+ // Check ancestor tree locks.
+ let mut current = path.to_string();
+ loop {
+ let parent = match current.rsplit_once('/') {
+ Some((p, _)) if !p.is_empty() => p.to_string(),
+ Some(_) if current != "/" => "/".to_string(),
+ _ => break,
+ };
+ let ancestor_lock = if parent == "/" {
+ format!("/{}", PATH_LOCK_FILE)
+ } else {
+ format!("{}/{}", parent, PATH_LOCK_FILE)
+ };
+ if let Ok(Some(token)) = self.provider.read_token(&ancestor_lock).await {
+ // Only Tree locks propagate to descendants.
+ if token.lock_type == PathLockKind::Tree
+ && (!ignore_stale || !self.is_stale(&token, now_ns))
+ {
+ return Ok(true);
+ }
+ }
+ current = parent;
+ }
+
+ Ok(false)
+ }
+
+ /// Return an observability snapshot.
+ pub async fn observe(&self) -> PathLockObserveSnapshot {
+ let metrics = self.metrics.read().await.clone();
+ PathLockObserveSnapshot {
+ active_locks: metrics.active_lock_count,
+ waiting_locks: metrics.waiting_lock_count,
+ stale_locks_removed: metrics.stale_tokens_removed,
+ conflicts: metrics.recent_conflicts,
+ }
+ }
+
+ /// Look up an owned lease by owner_id for cross-FFI lease operations.
+ pub async fn get_owned_lease(&self, owner_id: &str) -> Option<OwnedPathLockLease> {
+ let registry = self.lease_registry.read().await;
+ registry.get_by_owner(owner_id).map(|entry| OwnedPathLockLease {
+ lease: entry.lease.clone(),
+ ownership_ref: entry.ownership_ref.clone(),
+ })
+ }
+
+ /// Look up an owned lease by opaque lease_ref for cross-FFI lease operations.
+ pub async fn get_owned_lease_by_ref(&self, lease_ref: &str) -> Option<OwnedPathLockLease> {
+ let registry = self.lease_registry.read().await;
+ registry.get_by_ref(lease_ref).map(|entry| OwnedPathLockLease {
+ lease: entry.lease.clone(),
+ ownership_ref: entry.ownership_ref.clone(),
+ })
+ }
+
+ /// Look up an owned lease only when its lifecycle capability matches.
+ pub async fn get_owned_lease_by_capability(
+ &self,
+ lease_ref: &str,
+ ownership_ref: &str,
+ ) -> Option<OwnedPathLockLease> {
+ let registry = self.lease_registry.read().await;
+ registry
+ .get_by_ref(lease_ref)
+ .filter(|entry| entry.ownership_ref == ownership_ref)
+ .map(|entry| OwnedPathLockLease {
+ lease: entry.lease.clone(),
+ ownership_ref: entry.ownership_ref.clone(),
+ })
+ }
+
+ /// Validate that an opaque lease reference exists and covers all requested paths.
+ pub async fn require_covered_lease_ref(
+ &self,
+ lease_ref: &str,
+ requests: &[PathLockRequest],
+ ) -> PathLockResult<()> {
+ let registry = self.lease_registry.read().await;
+ let entry = registry.get_by_ref(lease_ref).ok_or_else(|| {
+ PathLockError::InvalidRequest(format!("unknown pathlock lease ref '{lease_ref}'"))
+ })?;
+ if requests.iter().all(|request| entry.lease.covers(request)) {
+ Ok(())
+ } else {
+ Err(PathLockError::InvalidRequest(format!(
+ "pathlock lease ref '{lease_ref}' does not cover the requested operation"
+ )))
+ }
+ }
+
+ /// Resolve automatic PathLock behavior from the current immutable FS context.
+ pub async fn resolve_auto_pathlock_action(
+ &self,
+ requests: &[PathLockRequest],
+ ) -> PathLockResult<AutoPathLockAction> {
+ let view = FsContextView::current();
+ if view.disable_auto_pathlock() {
+ return Ok(AutoPathLockAction::Disabled);
+ }
+ let Some(lease_ref) = view.pathlock_lease_ref() else {
+ return Ok(AutoPathLockAction::Acquire);
+ };
+ let lease = self
+ .get_owned_lease_by_ref(lease_ref)
+ .await
+ .ok_or_else(|| {
+ PathLockError::InvalidRequest(format!(
+ "unknown pathlock lease ref '{lease_ref}'"
+ ))
+ })?;
+ if requests.iter().all(|request| lease.lease.covers(request)) {
+ Ok(AutoPathLockAction::Covered(lease))
+ } else {
+ Err(PathLockError::InvalidRequest(format!(
+ "pathlock lease ref '{lease_ref}' does not cover the requested operation"
+ )))
+ }
+ }
+
+ /// Return a reference to the metrics for external reading.
+ pub async fn metrics_snapshot(&self) -> LockMetrics {
+ self.metrics.read().await.clone()
+ }
+}
+
+#[cfg(test)]
+mod tests {
+ use super::*;
+ use async_trait::async_trait;
+ use crate::plugins::memfs::MemFileSystem;
+ use std::sync::atomic::{AtomicBool, Ordering};
+
+ struct FailNextRemoveProvider {
+ inner: crate::lock::provider::MemoryPathLockProvider,
+ fail_next_read: AtomicBool,
+ fail_next_remove: AtomicBool,
+ return_false_next_remove: AtomicBool,
+ }
+
+ impl FailNextRemoveProvider {
+ /// Build a memory provider whose next token read fails.
+ fn with_read_failure() -> Self {
+ Self {
+ inner: crate::lock::provider::MemoryPathLockProvider::new(),
+ fail_next_read: AtomicBool::new(true),
+ fail_next_remove: AtomicBool::new(false),
+ return_false_next_remove: AtomicBool::new(false),
+ }
+ }
+
+ }
+
+ #[async_trait]
+ impl PathLockProvider for FailNextRemoveProvider {
+ fn name(&self) -> &'static str {
+ "fail-next-remove"
+ }
+
+ async fn read_token(&self, lock_path: &str) -> PathLockResult<Option<LockToken>> {
+ if self.fail_next_read.swap(false, Ordering::SeqCst) {
+ return Err(PathLockError::Io("injected read failure".to_string()));
+ }
+ self.inner.read_token(lock_path).await
+ }
+
+ async fn try_create_token(
+ &self,
+ lock_path: &str,
+ token: &LockToken,
+ ) -> PathLockResult<()> {
+ self.inner.try_create_token(lock_path, token).await
+ }
+
+ async fn compare_and_write_token(
+ &self,
+ lock_path: &str,
+ expected: &LockToken,
+ replacement: &LockToken,
+ ) -> PathLockResult<bool> {
+ self.inner
+ .compare_and_write_token(lock_path, expected, replacement)
+ .await
+ }
+
+ async fn refresh_token(
+ &self,
+ lock_path: &str,
+ owner_id: &str,
+ time_ns: u128,
+ ) -> PathLockResult<bool> {
+ self.inner
+ .refresh_token(lock_path, owner_id, time_ns)
+ .await
+ }
+
+ async fn remove_token(
+ &self,
+ lock_path: &str,
+ owner_id: &str,
+ ) -> PathLockResult<bool> {
+ if self.return_false_next_remove.swap(false, Ordering::SeqCst) {
+ return Ok(false);
+ }
+ if self.fail_next_remove.swap(false, Ordering::SeqCst) {
+ return Err(PathLockError::Io("injected remove failure".to_string()));
+ }
+ self.inner.remove_token(lock_path, owner_id).await
+ }
+
+ async fn scan_descendant_locks(&self, root: &str) -> PathLockResult<Vec<String>> {
+ self.inner.scan_descendant_locks(root).await
+ }
+ }
+
+ /// Build a manager backed by the real in-memory filesystem.
+ async fn make_manager() -> PathLockManager {
+ make_manager_with_config(PathLockConfig::default()).await
+ }
+
+ /// Build a manager with custom lock configuration.
+ async fn make_manager_with_config(config: PathLockConfig) -> PathLockManager {
+ let fs = Arc::new(MemFileSystem::new());
+ fs.mkdir("/data", 0o755).await.unwrap();
+ fs.mkdir("/data/sub", 0o755).await.unwrap();
+ let provider = Arc::new(crate::lock::provider::MemoryPathLockProvider::new());
+ PathLockManager::new(fs, provider, config)
+ }
+
+ /// Build a manager and expose its real in-memory filesystem.
+ async fn make_manager_with_fs() -> (PathLockManager, Arc<MemFileSystem>) {
+ let fs = Arc::new(MemFileSystem::new());
+ fs.mkdir("/data", 0o755).await.unwrap();
+ let provider = Arc::new(crate::lock::provider::MemoryPathLockProvider::new());
+ (
+ PathLockManager::new(fs.clone(), provider, PathLockConfig::default()),
+ fs,
+ )
+ }
+
+ #[tokio::test]
+ async fn acquire_exact_reentrant_requires_local_owned_capability() {
+ let mgr = make_manager().await;
+ let lease1 = mgr
+ .acquire_exact("/data/file.txt", Duration::from_secs(1), None)
+ .await
+ .unwrap();
+ let capability = (
+ lease1.lease.lease_ref.as_str(),
+ lease1.ownership_ref.as_str(),
+ );
+ let lease2 = mgr
+ .acquire_exact("/data/file.txt", Duration::from_secs(1), Some(capability))
+ .await
+ .unwrap();
+ assert_eq!(lease1.lease.lock_paths, lease2.lease.lock_paths);
+
+ mgr.release(&lease2).await.unwrap();
+ assert!(matches!(
+ mgr.acquire_exact("/data/file.txt", Duration::ZERO, None).await,
+ Err(PathLockError::Timeout { .. })
+ ));
+
+ mgr.release(&lease1).await.unwrap();
+ assert!(mgr
+ .acquire_exact("/data/file.txt", Duration::ZERO, None)
+ .await
+ .is_ok());
+ }
+
+ /// Keep coverage for paths that remain after a partial lease release.
+ #[tokio::test]
+ async fn release_selected_preserves_remaining_coverage() {
+ let mgr = make_manager().await;
+ let lease = mgr
+ .acquire_exact_batch(
+ &["/data/a.txt".to_string(), "/data/b.txt".to_string()],
+ Duration::ZERO,
+ None,
+ )
+ .await
+ .unwrap();
+ let released_lock_path = lease.lease.lock_paths[0].clone();
+
+ mgr.release_selected(&lease, &[released_lock_path])
+ .await
+ .unwrap();
+
+ assert!(mgr
+ .require_covered_lease_ref(
+ &lease.lease.lease_ref,
+ &[PathLockRequest {
+ path: "/data/b.txt".to_string(),
+ kind: PathLockKind::Exact,
+ }],
+ )
+ .await
+ .is_ok());
+ mgr.release(&lease).await.unwrap();
+ }
+
+ #[tokio::test]
+ async fn failed_batch_rolls_back_same_owner_tree_upgrade() {
+ let mgr = make_manager().await;
+ let exact = mgr
+ .acquire_exact("/data/sub", Duration::ZERO, None)
+ .await
+ .unwrap();
+ let blocker = mgr
+ .acquire_exact("/data/z.txt", Duration::ZERO, None)
+ .await
+ .unwrap();
+ let capability = (
+ exact.lease.lease_ref.as_str(),
+ exact.ownership_ref.as_str(),
+ );
+
+ let result = mgr
+ .acquire_batch(
+ &[
+ PathLockRequest {
+ path: "/data/sub".to_string(),
+ kind: PathLockKind::Tree,
+ },
+ PathLockRequest {
+ path: "/data/z.txt".to_string(),
+ kind: PathLockKind::Exact,
+ },
+ ],
+ Duration::ZERO,
+ Some(capability),
+ )
+ .await;
+
+ assert!(matches!(result, Err(PathLockError::Timeout { .. })));
+ let token = mgr
+ .provider
+ .read_token("/data/sub/.path.ovlock")
+ .await
+ .unwrap()
+ .unwrap();
+ assert_eq!(token.lock_type, PathLockKind::Exact);
+
+ mgr.release(&blocker).await.unwrap();
+ mgr.release(&exact).await.unwrap();
+ }
+
+ #[tokio::test]
+ async fn missing_exact_and_same_path_tree_conflict_in_both_orders() {
+ let (mgr, _) = make_manager_with_fs().await;
+ let exact = mgr
+ .acquire_exact("/data/new", Duration::ZERO, None)
+ .await
+ .unwrap();
+ assert!(matches!(
+ mgr.acquire_tree("/data/new", Duration::ZERO, None).await,
+ Err(PathLockError::Timeout { .. })
+ ));
+ mgr.release(&exact).await.unwrap();
+
+ let tree = mgr
+ .acquire_tree("/data/other", Duration::ZERO, None)
+ .await
+ .unwrap();
+ assert!(matches!(
+ mgr.acquire_exact("/data/other", Duration::ZERO, None).await,
+ Err(PathLockError::Timeout { .. })
+ ));
+ mgr.release(&tree).await.unwrap();
+ }
+
+ #[tokio::test]
+ async fn handoff_and_adopt() {
+ let mgr = make_manager().await;
+ let lease = mgr
+ .acquire_tree("/data/sub", Duration::from_secs(1), None)
+ .await
+ .unwrap();
+ let handoff = mgr.to_handoff(&lease);
+ mgr.handoff(&lease).await.unwrap();
+
+ let adopted = mgr.adopt(&handoff).await.unwrap();
+ assert_eq!(adopted.lease.owner_id, lease.lease.owner_id);
+ assert_eq!(adopted.lease.lock_paths, handoff.lock_paths);
+ }
+
+ #[tokio::test]
+ async fn opaque_lease_ref_must_cover_requested_path() {
+ let mgr = make_manager().await;
+ let lease = mgr
+ .acquire_tree("/data", Duration::from_secs(1), None)
+ .await
+ .unwrap();
+
+ assert_ne!(lease.lease.lease_ref, lease.lease.owner_id);
+ assert!(mgr
+ .require_covered_lease_ref(
+ &lease.lease.owner_id,
+ &[PathLockRequest {
+ path: "/data/sub/file.txt".to_string(),
+ kind: PathLockKind::Exact,
+ }],
+ )
+ .await
+ .is_err());
+ assert!(mgr
+ .require_covered_lease_ref(
+ &lease.lease.lease_ref,
+ &[PathLockRequest {
+ path: "/data/sub/file.txt".to_string(),
+ kind: PathLockKind::Exact,
+ }],
+ )
+ .await
+ .is_ok());
+ assert!(mgr
+ .require_covered_lease_ref(
+ &lease.lease.lease_ref,
+ &[PathLockRequest {
+ path: "/other/file.txt".to_string(),
+ kind: PathLockKind::Exact,
+ }],
+ )
+ .await
+ .is_err());
+ }
+
+ #[tokio::test]
+ async fn handoff_stops_source_refresh_until_adopted() {
+ let mgr = make_manager_with_config(PathLockConfig {
+ lock_expire_secs: 0.03,
+ ..PathLockConfig::default()
+ })
+ .await;
+ let lease = mgr
+ .acquire_tree("/data/sub", Duration::from_secs(1), None)
+ .await
+ .unwrap();
+ let lock_path = lease.lease.lock_paths[0].clone();
+ mgr.handoff(&lease).await.unwrap();
+
+ let before = mgr
+ .provider
+ .read_token(&lock_path)
+ .await
+ .unwrap()
+ .unwrap()
+ .time_ns;
+ tokio::time::sleep(Duration::from_millis(25)).await;
+
+ let after = mgr
+ .provider
+ .read_token(&lock_path)
+ .await
+ .unwrap()
+ .unwrap()
+ .time_ns;
+ assert_eq!(after, before);
+ assert!(mgr
+ .get_owned_lease_by_ref(&lease.lease.lease_ref)
+ .await
+ .is_none());
+
+ let handoff = mgr.to_handoff(&lease);
+ let adopted = mgr.adopt(&handoff).await.unwrap();
+ assert_eq!(adopted.lease.owner_id, lease.lease.owner_id);
+ }
+
+ #[tokio::test]
+ async fn is_locked_detects_root_tree_lock() {
+ let mgr = make_manager().await;
+ assert!(!mgr.is_locked("/data/file.txt", true).await.unwrap());
+ let _root = mgr
+ .acquire_tree("/", Duration::ZERO, None)
+ .await
+ .unwrap();
+ assert!(mgr.is_locked("/data/file.txt", true).await.unwrap());
+ }
+
+ #[tokio::test]
+ async fn provider_io_error_is_not_retried() {
+ let fs = Arc::new(MemFileSystem::new());
+ fs.mkdir("/data", 0o755).await.unwrap();
+ let provider = Arc::new(FailNextRemoveProvider::with_read_failure());
+ let mgr = PathLockManager::new(fs, provider, PathLockConfig::default());
+
+ assert!(matches!(
+ mgr.acquire_exact("/data/file.txt", Duration::ZERO, None)
+ .await,
+ Err(PathLockError::Io(message)) if message == "injected read failure"
+ ));
+ }
+}
diff --git a/crates/ragfs/src/lock/metrics.rs b/crates/ragfs/src/lock/metrics.rs
new file mode 100644
index 000000000..9a60bff9c
--- /dev/null
+++ b/crates/ragfs/src/lock/metrics.rs
@@ -0,0 +1,42 @@
+//! Lock observability metrics.
+
+use crate::lock::types::PathLockConflict;
+
+/// Max number of recent conflicts retained for observability.
+const MAX_RECENT_CONFLICTS: usize = 32;
+
+/// Runtime metrics collected by `PathLockManager`.
+#[derive(Debug, Clone, Default)]
+pub struct LockMetrics {
+ /// Current number of active (held) locks.
+ pub active_lock_count: usize,
+ /// Current number of waiting lock requests.
+ pub waiting_lock_count: usize,
+ /// Cumulative count of stale tokens removed during acquire.
+ pub stale_tokens_removed: usize,
+ /// Cumulative count of stale leases released by heartbeat.
+ pub stale_leases_released: usize,
+ /// Cumulative count of stale cleanup failures.
+ pub stale_cleanup_failures: usize,
+ /// Cumulative count of descendant scan operations.
+ pub descendant_scan_count: usize,
+ /// Total milliseconds spent in descendant scans.
+ pub descendant_scan_duration_ms: u64,
+ /// Total milliseconds spent waiting for locks.
+ pub wait_duration_ms: u64,
+ /// Count of conflicts by type (exact/exact, tree/exact, etc.).
+ pub conflict_count: usize,
+ /// Recent conflicts for observability (ring buffer).
+ pub recent_conflicts: Vec<PathLockConflict>,
+}
+
+impl LockMetrics {
+ /// Record a conflict, keeping at most `MAX_RECENT_CONFLICTS` entries.
+ pub fn record_conflict(&mut self, conflict: PathLockConflict) {
+ self.conflict_count += 1;
+ if self.recent_conflicts.len() >= MAX_RECENT_CONFLICTS {
+ self.recent_conflicts.remove(0);
+ }
+ self.recent_conflicts.push(conflict);
+ }
+}
diff --git a/crates/ragfs/src/lock/mod.rs b/crates/ragfs/src/lock/mod.rs
new file mode 100644
index 000000000..e50e3c9cc
--- /dev/null
+++ b/crates/ragfs/src/lock/mod.rs
@@ -0,0 +1,32 @@
+//! PathLock subsystem — native file-system-level locking protocol.
+//!
+//! This module provides exact-path and tree-path locks backed by lock files
+//! (`.path.ovlock` / `.exact.ovlock.*`) on the underlying filesystem.
+//!
+//! # Architecture
+//!
+//! - [`PathLockManager`] is the single source of truth for lock semantics.
+//! - [`PathLockProvider`] is the storage abstraction (memory or filesystem).
+//! - [`PathLockWrappedFS`] is a convenience wrapper that auto-acquires locks
+//! for simple file operations.
+//! - [`LockPathResolver`] computes lock-file paths.
+//! - [`LockTokenCodec`] encodes/decodes lock tokens.
+
+pub mod codec;
+pub mod manager;
+pub mod metrics;
+pub mod provider;
+pub mod resolver;
+pub mod types;
+pub mod wrapper;
+
+pub use codec::LockTokenCodec;
+pub use manager::{AutoPathLockAction, PathLockConfig, PathLockManager};
+pub use metrics::LockMetrics;
+pub use provider::{FilesystemPathLockProvider, MemoryPathLockProvider, PathLockProvider};
+pub use resolver::LockPathResolver;
+pub use types::{
+ BorrowedPathLockLease, LockToken, OwnedPathLockLease, PathLockConflict, PathLockHandoffRef,
+ PathLockKind, PathLockLease, PathLockObserveSnapshot, PathLockRequest, PathLockResult,
+};
+pub use wrapper::PathLockWrappedFS;
diff --git a/crates/ragfs/src/lock/provider.rs b/crates/ragfs/src/lock/provider.rs
new file mode 100644
index 000000000..76bbe0396
--- /dev/null
+++ b/crates/ragfs/src/lock/provider.rs
@@ -0,0 +1,338 @@
+//! PathLockProvider trait and built-in implementations.
+//!
+//! The provider is a pure storage abstraction — it does not implement lock semantics
+//! (conflict detection, waiting, etc.). Those belong to `PathLockManager`.
+
+use std::collections::HashMap;
+use std::sync::Arc;
+
+use async_trait::async_trait;
+use tokio::sync::RwLock;
+
+use crate::core::internal_names::is_hidden_runtime_lock_name;
+use crate::core::FileSystem;
+
+use super::codec::LockTokenCodec;
+use super::types::{LockToken, PathLockError, PathLockResult};
+
+/// Storage abstraction for lock tokens. Only `PathLockManager` should call these methods.
+#[async_trait]
+pub trait PathLockProvider: Send + Sync {
+ /// Human-readable provider name for config/logging/metrics.
+ fn name(&self) -> &'static str;
+
+ /// Read the token at `lock_path`, returning `None` if no token exists.
+ async fn read_token(&self, lock_path: &str) -> PathLockResult<Option<LockToken>>;
+
+ /// Atomically create a token at `lock_path`. Must fail if a token already exists
+ /// (unless it is stale and can be cleaned up by the manager).
+ async fn try_create_token(&self, lock_path: &str, token: &LockToken) -> PathLockResult<()>;
+
+ /// Atomically replace one exact token value.
+ async fn compare_and_write_token(
+ &self,
+ lock_path: &str,
+ expected: &LockToken,
+ replacement: &LockToken,
+ ) -> PathLockResult<bool>;
+
+ /// Refresh the timestamp of an existing token owned by `owner_id`.
+ /// Returns `true` if the token was refreshed, `false` if not found or wrong owner.
+ async fn refresh_token(
+ &self,
+ lock_path: &str,
+ owner_id: &str,
+ time_ns: u128,
+ ) -> PathLockResult<bool>;
+
+ /// Remove the token at `lock_path` if owned by `owner_id`.
+ /// Returns `true` if removed, `false` if not found or wrong owner.
+ async fn remove_token(&self, lock_path: &str, owner_id: &str) -> PathLockResult<bool>;
+
+ /// Scan all descendant lock paths under `root`.
+ async fn scan_descendant_locks(&self, root: &str) -> PathLockResult<Vec<String>>;
+}
+
+// ── Memory provider ──
+
+/// In-process lock table backed by a `HashMap`. Single-process only.
+pub struct MemoryPathLockProvider {
+ tokens: RwLock<HashMap<String, LockToken>>,
+}
+
+impl MemoryPathLockProvider {
+ /// Create an empty in-memory provider.
+ pub fn new() -> Self {
+ Self {
+ tokens: RwLock::new(HashMap::new()),
+ }
+ }
+}
+
+impl Default for MemoryPathLockProvider {
+ fn default() -> Self {
+ Self::new()
+ }
+}
+
+#[async_trait]
+impl PathLockProvider for MemoryPathLockProvider {
+ fn name(&self) -> &'static str {
+ "memory"
+ }
+
+ async fn read_token(&self, lock_path: &str) -> PathLockResult<Option<LockToken>> {
+ Ok(self.tokens.read().await.get(lock_path).cloned())
+ }
+
+ async fn try_create_token(&self, lock_path: &str, token: &LockToken) -> PathLockResult<()> {
+ let mut tokens = self.tokens.write().await;
+ if tokens.contains_key(lock_path) {
+ return Err(PathLockError::Conflict {
+ lock_path: lock_path.to_string(),
+ owner: tokens[lock_path].owner_id.clone(),
+ kind: tokens[lock_path].lock_type,
+ });
+ }
+ tokens.insert(lock_path.to_string(), token.clone());
+ Ok(())
+ }
+
+ async fn compare_and_write_token(
+ &self,
+ lock_path: &str,
+ expected: &LockToken,
+ replacement: &LockToken,
+ ) -> PathLockResult<bool> {
+ let mut tokens = self.tokens.write().await;
+ match tokens.get(lock_path) {
+ Some(token) if token == expected => {
+ tokens.insert(lock_path.to_string(), replacement.clone());
+ Ok(true)
+ }
+ _ => Ok(false),
+ }
+ }
+
+ async fn refresh_token(
+ &self,
+ lock_path: &str,
+ owner_id: &str,
+ time_ns: u128,
+ ) -> PathLockResult<bool> {
+ let mut tokens = self.tokens.write().await;
+ match tokens.get_mut(lock_path) {
+ Some(token) if token.owner_id == owner_id => {
+ token.time_ns = time_ns;
+ Ok(true)
+ }
+ _ => Ok(false),
+ }
+ }
+
+ async fn remove_token(&self, lock_path: &str, owner_id: &str) -> PathLockResult<bool> {
+ let mut tokens = self.tokens.write().await;
+ match tokens.get(lock_path) {
+ Some(token) if token.owner_id == owner_id => {
+ tokens.remove(lock_path);
+ Ok(true)
+ }
+ _ => Ok(false),
+ }
+ }
+
+ async fn scan_descendant_locks(&self, root: &str) -> PathLockResult<Vec<String>> {
+ let prefix = if root.ends_with('/') {
+ root.to_string()
+ } else {
+ format!("{}/", root)
+ };
+ Ok(self
+ .tokens
+ .read()
+ .await
+ .keys()
+ .filter(|k| k.starts_with(&prefix))
+ .cloned()
+ .collect())
+ }
+}
+
+// ── Filesystem provider ──
+
+/// Lock provider that stores tokens as files on the underlying filesystem.
+pub struct FilesystemPathLockProvider {
+ fs: Arc<dyn FileSystem>,
+}
+
+impl FilesystemPathLockProvider {
+ /// Create a filesystem-backed provider.
+ pub fn new(fs: Arc<dyn FileSystem>) -> Self {
+ Self { fs }
+ }
+
+ /// Read raw token bytes from `lock_path`, returning `None` if no token exists.
+ async fn read_token_raw(&self, lock_path: &str) -> PathLockResult<Option<Vec<u8>>> {
+ match self.fs.read(lock_path, 0, 0).await {
+ Ok(data) => Ok(Some(data)),
+ Err(e) => {
+ if matches!(
+ e,
+ crate::core::Error::NotFound(_) | crate::core::Error::MountPointNotFound(_)
+ ) {
+ Ok(None)
+ } else {
+ Err(PathLockError::Io(format!(
+ "failed to read lock token at '{lock_path}': {e}"
+ )))
+ }
+ }
+ }
+ }
+}
+
+#[async_trait]
+impl PathLockProvider for FilesystemPathLockProvider {
+ fn name(&self) -> &'static str {
+ "filesystem"
+ }
+
+ async fn read_token(&self, lock_path: &str) -> PathLockResult<Option<LockToken>> {
+ match self.read_token_raw(lock_path).await? {
+ Some(data) => {
+ let raw = String::from_utf8_lossy(&data).trim().to_string();
+ if raw.is_empty() {
+ return Ok(None);
+ }
+ LockTokenCodec::decode(&raw).map(Some)
+ }
+ None => Ok(None),
+ }
+ }
+
+ async fn try_create_token(&self, lock_path: &str, token: &LockToken) -> PathLockResult<()> {
+ use crate::core::WriteFlag;
+
+ let encoded = LockTokenCodec::encode(token);
+ match self
+ .fs
+ .write(lock_path, encoded.as_bytes(), 0, WriteFlag::CreateNew)
+ .await
+ {
+ Ok(_) => Ok(()),
+ Err(_) => {
+ // Already exists — read and check if stale.
+ let existing = self.read_token(lock_path).await?;
+ match existing {
+ Some(t) => Err(PathLockError::Conflict {
+ lock_path: lock_path.to_string(),
+ owner: t.owner_id,
+ kind: t.lock_type,
+ }),
+ None => Err(PathLockError::Io(format!(
+ "failed to create lock token at {lock_path}"
+ ))),
+ }
+ }
+ }
+ }
+
+ async fn compare_and_write_token(
+ &self,
+ lock_path: &str,
+ expected: &LockToken,
+ replacement: &LockToken,
+ ) -> PathLockResult<bool> {
+ let expected = LockTokenCodec::encode(expected);
+ let replacement = LockTokenCodec::encode(replacement);
+ self.fs
+ .compare_and_write(lock_path, expected.as_bytes(), replacement.as_bytes())
+ .await
+ .map_err(|e| PathLockError::Io(format!("token CAS failed: {e}")))
+ }
+
+ async fn refresh_token(
+ &self,
+ lock_path: &str,
+ owner_id: &str,
+ time_ns: u128,
+ ) -> PathLockResult<bool> {
+ let Some(raw) = self.read_token_raw(lock_path).await? else {
+ return Ok(false);
+ };
+ let token = LockTokenCodec::decode(&String::from_utf8_lossy(&raw).trim())?;
+ if token.owner_id != owner_id {
+ return Ok(false);
+ }
+ let new_token = LockToken {
+ owner_id: owner_id.to_string(),
+ time_ns,
+ lock_type: token.lock_type,
+ };
+ let encoded = LockTokenCodec::encode(&new_token);
+ self.fs
+ .compare_and_write(lock_path, &raw, encoded.as_bytes())
+ .await
+ .map_err(|e| PathLockError::Io(format!("refresh CAS failed: {e}")))
+ }
+
+ async fn remove_token(&self, lock_path: &str, owner_id: &str) -> PathLockResult<bool> {
+ let Some(raw) = self.read_token_raw(lock_path).await? else {
+ return Ok(false);
+ };
+ let token = LockTokenCodec::decode(&String::from_utf8_lossy(&raw).trim())?;
+ if token.owner_id != owner_id {
+ return Ok(false);
+ }
+ self.fs
+ .compare_and_remove(lock_path, &raw)
+ .await
+ .map_err(|e| PathLockError::Io(format!("remove CAS failed: {e}")))
+ }
+
+ async fn scan_descendant_locks(&self, root: &str) -> PathLockResult<Vec<String>> {
+ let mut result = Vec::new();
+ self.scan_recursive(root, &mut result).await?;
+ Ok(result)
+ }
+}
+
+impl FilesystemPathLockProvider {
+ /// Recursively scan a directory for `.path.ovlock` and `.exact.ovlock.*` files.
+ fn is_lock_file(name: &str) -> bool {
+ is_hidden_runtime_lock_name(name)
+ }
+
+ async fn scan_recursive(
+ &self,
+ dir: &str,
+ result: &mut Vec<String>,
+ ) -> PathLockResult<()> {
+ let entries = match self.fs.read_internal_dir(dir).await {
+ Ok(entries) => entries,
+ Err(crate::core::Error::NotFound(_) | crate::core::Error::NotADirectory(_)) => {
+ return Ok(());
+ }
+ Err(error) => {
+ return Err(PathLockError::Io(format!(
+ "failed to scan lock directory '{dir}': {error}"
+ )));
+ }
+ };
+
+ for entry in entries {
+ let child_path = if dir.ends_with('/') {
+ format!("{}{}", dir, entry.name)
+ } else {
+ format!("{}/{}", dir, entry.name)
+ };
+
+ if Self::is_lock_file(&entry.name) {
+ result.push(child_path);
+ } else if entry.is_dir {
+ Box::pin(self.scan_recursive(&child_path, result)).await?;
+ }
+ }
+ Ok(())
+ }
+}
diff --git a/crates/ragfs/src/lock/resolver.rs b/crates/ragfs/src/lock/resolver.rs
new file mode 100644
index 000000000..2f32da81e
--- /dev/null
+++ b/crates/ragfs/src/lock/resolver.rs
@@ -0,0 +1,203 @@
+//! Lock-path resolver — computes `.path.ovlock` and `.exact.ovlock.*` paths.
+
+use std::sync::Arc;
+
+use sha1::{Digest, Sha1};
+
+use crate::core::internal_names::{EXACT_LOCK_FILE_PREFIX, PATH_LOCK_FILE};
+use crate::core::FileSystem;
+
+use super::types::PathLockResult;
+
+/// Exact-lock paths resolved from one real path classification.
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub(crate) struct ResolvedExactPaths {
+ /// Lock path used for the actual exact token creation.
+ pub acquire_lock_path: String,
+ /// Conservative conflict set checked before and after token creation.
+ pub conflict_paths: Vec<String>,
+}
+
+/// Computes lock-file paths for exact and tree locks.
+pub struct LockPathResolver {
+ /// Filesystem used for `stat` calls to determine is_dir.
+ pub(crate) fs: Arc<dyn FileSystem>,
+}
+
+impl LockPathResolver {
+ /// Create a new resolver backed by `fs`.
+ pub fn new(fs: Arc<dyn FileSystem>) -> Self {
+ Self { fs }
+ }
+
+ /// Compute exact lock paths for `path`.
+ ///
+ /// - Existing directory → `{path}/.path.ovlock`
+ /// - File or non-existent path → `{parent}/.exact.ovlock.<safe_name>.<sha1-prefix>`
+ pub async fn resolve_exact_lock_paths(&self, path: &str) -> PathLockResult<Vec<String>> {
+ Ok(vec![self.resolve_exact_lock_path(path).await?])
+ }
+
+ /// Compute every lock-file path that can represent an exact lock for conflict checks.
+ pub async fn resolve_exact_conflict_paths(
+ &self,
+ path: &str,
+ ) -> PathLockResult<Vec<String>> {
+ Ok(self.resolve_exact_paths(path).await?.conflict_paths)
+ }
+
+ /// Compute the primary lock-file path used when acquiring one exact lock.
+ pub async fn resolve_exact_lock_path(&self, path: &str) -> PathLockResult<String> {
+ Ok(self.resolve_exact_paths(path).await?.acquire_lock_path)
+ }
+
+ /// Resolve the exact acquire path and its conservative conflict set using one `stat`.
+ pub(crate) async fn resolve_exact_paths(&self, path: &str) -> PathLockResult<ResolvedExactPaths> {
+ let stat_result = self.fs.stat(path).await;
+ let acquire_lock_path = match stat_result {
+ Ok(info) if info.is_dir => path_lock_path(path),
+ _ => prefixed_exact_lock_path(path),
+ };
+ let conflict_paths = if acquire_lock_path == path_lock_path(path) {
+ vec![acquire_lock_path.clone(), prefixed_exact_lock_path(path)]
+ } else {
+ vec![acquire_lock_path.clone(), path_lock_path(path)]
+ };
+ Ok(ResolvedExactPaths {
+ acquire_lock_path,
+ conflict_paths,
+ })
+ }
+
+ /// Compute the tree lock path for `path`.
+ ///
+ /// - Regular directory or missing path → `{path}/.path.ovlock`
+ /// - Existing file path → parent directory sidecar
+ pub async fn resolve_tree_lock_path(&self, path: &str) -> PathLockResult<String> {
+ let stat_result = self.fs.stat(path).await;
+ match stat_result {
+ Ok(info) if !info.is_dir => {
+ // Existing file: use parent sidecar to avoid `{file}/.path.ovlock`.
+ Ok(prefixed_exact_lock_path(path))
+ }
+ _ => Ok(path_lock_path(path)),
+ }
+ }
+}
+
+/// Return the `.path.ovlock` path for one target.
+fn path_lock_path(path: &str) -> String {
+ format!("{}/{}", path.trim_end_matches('/'), PATH_LOCK_FILE)
+}
+
+/// Return the legacy-compatible prefixed exact sidecar path.
+fn prefixed_exact_lock_path(path: &str) -> String {
+ let (parent, name) = split_parent_name(path);
+ format!(
+ "{}/{}{}.{}",
+ parent,
+ EXACT_LOCK_FILE_PREFIX,
+ safe_name(name),
+ hash_prefix(path)
+ )
+}
+
+/// Split a path into (parent_dir, basename).
+fn split_parent_name(path: &str) -> (String, &str) {
+ let trimmed = path.trim_end_matches('/');
+ match trimmed.rsplit_once('/') {
+ Some((parent, name)) if !parent.is_empty() => (parent.to_string(), name),
+ Some((_, name)) => ("/".to_string(), name),
+ None => ("/".to_string(), trimmed),
+ }
+}
+
+/// Sanitize a filename exactly like the legacy Python pathlock protocol.
+fn safe_name(name: &str) -> String {
+ let mut sanitized = String::new();
+ let mut replacing = false;
+ for c in name.chars() {
+ if c.is_ascii_alphanumeric() || matches!(c, '.' | '_' | '-') {
+ sanitized.push(c);
+ replacing = false;
+ } else if !replacing {
+ sanitized.push('_');
+ replacing = true;
+ }
+ }
+ let sanitized = sanitized.trim_matches(['.', '_']);
+ let sanitized = if sanitized.is_empty() {
+ "path"
+ } else {
+ sanitized
+ };
+ sanitized.chars().take(80).collect()
+}
+
+/// First 16 hex chars of SHA-1 of the full backend path.
+fn hash_prefix(path: &str) -> String {
+ let digest = Sha1::digest(path.as_bytes());
+ digest[..8].iter().map(|b| format!("{:02x}", b)).collect::<String>()
+}
+
+#[cfg(test)]
+mod tests {
+ use super::*;
+ use crate::core::WriteFlag;
+ use crate::plugins::memfs::MemFileSystem;
+
+ /// Build the real in-memory filesystem used by resolver tests.
+ async fn memfs() -> Arc<MemFileSystem> {
+ let fs = Arc::new(MemFileSystem::new());
+ fs.mkdir("/data", 0o755).await.unwrap();
+ fs
+ }
+
+ #[tokio::test]
+ async fn resolver_uses_path_lock_for_directories_and_sidecars_for_files() {
+ let fs = memfs().await;
+ fs.mkdir("/data/dir", 0o755).await.unwrap();
+ fs.write("/data/file.txt", b"", 0, WriteFlag::Create)
+ .await
+ .unwrap();
+ let resolver = LockPathResolver::new(fs);
+
+ assert_eq!(
+ resolver.resolve_exact_lock_paths("/data/dir").await.unwrap(),
+ vec!["/data/dir/.path.ovlock".to_string()]
+ );
+ assert_eq!(
+ resolver.resolve_tree_lock_path("/data/dir").await.unwrap(),
+ "/data/dir/.path.ovlock"
+ );
+
+ let exact_file = resolver
+ .resolve_exact_lock_paths("/data/file.txt")
+ .await
+ .unwrap();
+ assert!(exact_file[0].starts_with("/data/.exact.ovlock.file.txt."));
+ assert!(resolver
+ .resolve_tree_lock_path("/data/file.txt")
+ .await
+ .unwrap()
+ .starts_with("/data/.exact.ovlock.file.txt."));
+ assert!(resolver
+ .resolve_exact_lock_paths("/data/new.txt")
+ .await
+ .unwrap()[0]
+ .starts_with("/data/.exact.ovlock.new.txt."));
+ }
+
+ #[test]
+ fn sidecar_name_matches_legacy_python_protocol() {
+ assert_eq!(safe_name("hello world"), "hello_world");
+ assert_eq!(safe_name("a/b"), "a_b");
+ assert_eq!(safe_name("ok.txt"), "ok.txt");
+ assert_eq!(safe_name("中文名"), "path");
+ assert_eq!(safe_name(""), "path");
+ assert_eq!(
+ prefixed_exact_lock_path("/data/中文 name..txt"),
+ "/data/.exact.ovlock.name..txt.591847f8876e86f7"
+ );
+ }
+}
diff --git a/crates/ragfs/src/lock/types.rs b/crates/ragfs/src/lock/types.rs
new file mode 100644
index 000000000..1bb1c34da
--- /dev/null
+++ b/crates/ragfs/src/lock/types.rs
@@ -0,0 +1,200 @@
+//! Data models for the PathLock subsystem.
+
+use serde::{Deserialize, Serialize};
+
+/// Lock kind: exact (single path) or tree (path + descendants).
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
+pub enum PathLockKind {
+ /// Exact-path lock.
+ Exact,
+ /// Tree lock covering the path and all descendants.
+ Tree,
+}
+
+impl PathLockKind {
+ /// Single-character encoding: `E` for Exact, `T` for Tree.
+ pub fn to_code(self) -> char {
+ match self {
+ PathLockKind::Exact => 'E',
+ PathLockKind::Tree => 'T',
+ }
+ }
+
+ /// Decode from a single character.
+ pub fn from_code(c: char) -> Option<Self> {
+ match c {
+ 'E' => Some(PathLockKind::Exact),
+ 'T' => Some(PathLockKind::Tree),
+ _ => None,
+ }
+ }
+}
+
+/// Structured lock token stored in lock files.
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct LockToken {
+ /// Owner identity (UUIDv4-style).
+ pub owner_id: String,
+ /// Nanosecond timestamp of last write/refresh.
+ pub time_ns: u128,
+ /// Lock type.
+ pub lock_type: PathLockKind,
+}
+
+/// Unified lease record (Rust-internal, exposed to Python as an opaque reference).
+#[derive(Debug, Clone)]
+pub struct PathLockLease {
+ /// Opaque lease reference used by callers; not equal to owner_id.
+ pub lease_ref: String,
+ /// Owner identity.
+ pub owner_id: String,
+ /// Lock-file paths held by this lease.
+ pub lock_paths: Vec<String>,
+ /// Original path coverage granted by the lease.
+ pub covered_paths: Vec<PathLockRequest>,
+}
+
+/// Owned lease — caller controls refresh/release/handoff lifecycle.
+#[derive(Debug, Clone)]
+pub struct OwnedPathLockLease {
+ /// Underlying lease data.
+ pub lease: PathLockLease,
+ /// Opaque capability required for lifecycle operations.
+ pub ownership_ref: String,
+}
+
+/// Borrowed lease — read-only proof that a lock is held, no lifecycle control.
+#[derive(Debug, Clone)]
+pub struct BorrowedPathLockLease {
+ /// Underlying lease data.
+ pub lease: PathLockLease,
+}
+
+/// Serializable handoff payload for cross-queue / cross-worker lock transfer.
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct PathLockHandoffRef {
+ /// Owner identity (preserved across handoff).
+ pub owner_id: String,
+ /// Lock-file paths held.
+ pub lock_paths: Vec<String>,
+ /// Original path coverage granted by the handed-off lease.
+ #[serde(default)]
+ pub covered_paths: Vec<PathLockRequest>,
+}
+
+/// A single lock request for batch acquire.
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct PathLockRequest {
+ /// Target path.
+ pub path: String,
+ /// Lock kind.
+ pub kind: PathLockKind,
+}
+
+impl PathLockLease {
+ /// Return true when this lease covers a requested operation.
+ pub fn covers(&self, request: &PathLockRequest) -> bool {
+ self.covered_paths
+ .iter()
+ .any(|held| request_is_covered_by(held, request))
+ }
+}
+
+/// Return true when a held request covers another requested operation.
+fn request_is_covered_by(held: &PathLockRequest, request: &PathLockRequest) -> bool {
+ match (held.kind, request.kind) {
+ (PathLockKind::Exact, PathLockKind::Exact) => normalize_path(&held.path) == normalize_path(&request.path),
+ (PathLockKind::Tree, _) => path_is_self_or_descendant(&request.path, &held.path),
+ (PathLockKind::Exact, PathLockKind::Tree) => false,
+ }
+}
+
+/// Normalize a path for simple lock coverage checks.
+fn normalize_path(path: &str) -> String {
+ let trimmed = path.trim_end_matches('/');
+ if trimmed.is_empty() {
+ "/".to_string()
+ } else {
+ trimmed.to_string()
+ }
+}
+
+/// Return true when `path` is equal to or under `ancestor`.
+fn path_is_self_or_descendant(path: &str, ancestor: &str) -> bool {
+ let path = normalize_path(path);
+ let ancestor = normalize_path(ancestor);
+ path == ancestor
+ || ancestor == "/"
+ || path
+ .strip_prefix(&ancestor)
+ .is_some_and(|suffix| suffix.starts_with('/'))
+}
+
+/// Snapshot of current lock state for observability.
+#[derive(Debug, Clone)]
+pub struct PathLockObserveSnapshot {
+ /// Number of active (held) locks.
+ pub active_locks: usize,
+ /// Number of waiting lock requests.
+ pub waiting_locks: usize,
+ /// Number of stale locks removed.
+ pub stale_locks_removed: usize,
+ /// Current conflicts.
+ pub conflicts: Vec<PathLockConflict>,
+}
+
+/// Description of a lock conflict.
+#[derive(Debug, Clone)]
+pub struct PathLockConflict {
+ /// Lock path where conflict occurred.
+ pub lock_path: String,
+ /// Owner of the conflicting lock.
+ pub conflicting_owner: String,
+ /// Kind of the conflicting lock.
+ pub conflicting_kind: PathLockKind,
+}
+
+/// PathLock-specific error type.
+#[derive(Debug, thiserror::Error)]
+pub enum PathLockError {
+ /// Lock conflict with another owner.
+ #[error("lock conflict on '{lock_path}': owned by '{owner}'")]
+ Conflict {
+ /// Lock path where conflict occurred.
+ lock_path: String,
+ /// Owner of the conflicting lock.
+ owner: String,
+ /// Kind of the conflicting lock from the original read snapshot.
+ kind: PathLockKind,
+ },
+
+ /// Timeout waiting for lock acquisition.
+ #[error("lock acquire timed out after {elapsed_ms}ms")]
+ Timeout {
+ /// Elapsed time in milliseconds.
+ elapsed_ms: u64,
+ },
+
+ /// I/O error during lock operation.
+ #[error("lock I/O error: {0}")]
+ Io(String),
+
+ /// Invalid lock token format.
+ #[error("invalid lock token: {0}")]
+ InvalidToken(String),
+
+ /// Invalid lock request supplied by a caller.
+ #[error("invalid lock request: {0}")]
+ InvalidRequest(String),
+
+ /// Handoff/adopt failure.
+ #[error("handoff/adopt failed: {0}")]
+ HandoffFailed(String),
+
+ /// Internal error.
+ #[error("lock internal error: {0}")]
+ Internal(String),
+}
+
+/// Result type alias for PathLock operations.
+pub type PathLockResult<T> = std::result::Result<T, PathLockError>;
diff --git a/crates/ragfs/src/lock/wrapper.rs b/crates/ragfs/src/lock/wrapper.rs
new file mode 100644
index 000000000..4e690884b
--- /dev/null
+++ b/crates/ragfs/src/lock/wrapper.rs
@@ -0,0 +1,368 @@
+//! PathLockWrappedFS — automatic lock acquisition for simple file operations.
+//!
+//! This wrapper sits between `StatsWrappedFS` and `MountableFS` in the stack.
+//! It auto-acquires locks for `create`, `write`, `truncate`, `remove`, `remove_all`,
+//! `rename`, and `replace`, then delegates to the inner filesystem.
+//!
+//! It is NOT a lock protocol implementation — all lock logic is delegated to
+//! `PathLockManager`.
+
+use std::sync::Arc;
+use std::time::Duration;
+
+use async_trait::async_trait;
+
+use crate::core::filesystem::FileSystem;
+use crate::core::internal_names::is_hidden_runtime_lock_name;
+use crate::core::types::{FileInfo, GlobPage, GrepResult, TreeEntry, WriteFlag};
+use crate::core::MountableFS;
+
+use super::manager::{AutoPathLockAction, PathLockManager};
+use super::types::{PathLockKind, PathLockRequest};
+
+/// Default timeout for auto-acquired locks.
+const AUTO_LOCK_TIMEOUT: Duration = Duration::ZERO;
+
+/// A `FileSystem` wrapper that auto-acquires path locks for mutating operations.
+pub struct PathLockWrappedFS {
+ /// The lock manager (single source of truth).
+ manager: Arc<PathLockManager>,
+ /// The inner filesystem.
+ inner: Arc<dyn FileSystem>,
+}
+
+impl PathLockWrappedFS {
+ /// Create a new PathLockWrappedFS.
+ pub fn new(manager: Arc<PathLockManager>, inner: Arc<dyn FileSystem>) -> Self {
+ Self { manager, inner }
+ }
+
+ /// Return the inner filesystem.
+ pub fn inner_fs(&self) -> &Arc<dyn FileSystem> {
+ &self.inner
+ }
+
+ /// Return true for virtual control paths and lock metadata that must not be auto-locked.
+ fn should_bypass_auto_lock(path: &str) -> bool {
+ path == "/queue"
+ || path.starts_with("/queue/")
+ || path == "/serverinfo"
+ || path.starts_with("/serverinfo/")
+ || path
+ .rsplit_once('/')
+ .map(|(_, name)| is_hidden_runtime_lock_name(name))
+ .unwrap_or_else(|| is_hidden_runtime_lock_name(path))
+ }
+
+ /// Check if auto-locking should be skipped for the current context.
+ ///
+ /// Returns `true` when auto-locking is disabled or an active lease covers the operation.
+ async fn should_skip_auto_lock(
+ &self,
+ requests: &[PathLockRequest],
+ ) -> crate::core::Result<bool> {
+ match self.manager.resolve_auto_pathlock_action(requests).await {
+ Ok(AutoPathLockAction::Disabled | AutoPathLockAction::Covered(_)) => Ok(true),
+ Ok(AutoPathLockAction::Acquire) => Ok(false),
+ Err(error) => Err(crate::core::Error::internal(format!(
+ "lock lease error: {error}"
+ ))),
+ }
+ }
+
+ /// Merge an operation result with its lock-release result.
+ fn merge_operation_and_release<T>(
+ operation: crate::core::Result<T>,
+ release: super::types::PathLockResult<()>,
+ ) -> crate::core::Result<T> {
+ match (operation, release) {
+ (Err(error), _) => Err(error),
+ (Ok(value), Ok(())) => Ok(value),
+ (Ok(_), Err(error)) => Err(crate::core::Error::internal(format!(
+ "lock release error: {error}"
+ ))),
+ }
+ }
+
+ /// Return whether the routed encryption wrapper owns locking for this write.
+ async fn encryption_handles_pathlock(&self, path: &str) -> bool {
+ let any = self.inner.as_ref() as &dyn std::any::Any;
+ match any.downcast_ref::<MountableFS>() {
+ Some(mountable) => mountable.encryption_handles_pathlock(path).await,
+ None => false,
+ }
+ }
+}
+
+#[async_trait]
+impl FileSystem for PathLockWrappedFS {
+ async fn create(&self, path: &str) -> crate::core::Result<()> {
+ if Self::should_bypass_auto_lock(path) || self.encryption_handles_pathlock(path).await {
+ return self.inner.create(path).await;
+ }
+ let requests = [PathLockRequest {
+ path: path.to_string(),
+ kind: PathLockKind::Exact,
+ }];
+ if self.should_skip_auto_lock(&requests).await? {
+ return self.inner.create(path).await;
+ }
+ let lease = self
+ .manager
+ .acquire_exact(path, AUTO_LOCK_TIMEOUT, None)
+ .await
+ .map_err(|e| crate::core::Error::internal(format!("lock error: {e}")))?;
+ let result = self.inner.create(path).await;
+ let release = self.manager.release(&lease).await;
+ Self::merge_operation_and_release(result, release)
+ }
+
+ async fn mkdir(&self, path: &str, mode: u32) -> crate::core::Result<()> {
+ self.inner.mkdir(path, mode).await
+ }
+
+ async fn remove(&self, path: &str) -> crate::core::Result<()> {
+ if Self::should_bypass_auto_lock(path) {
+ return self.inner.remove(path).await;
+ }
+ let requests = [PathLockRequest {
+ path: path.to_string(),
+ kind: PathLockKind::Exact,
+ }];
+ if self.should_skip_auto_lock(&requests).await? {
+ return self.inner.remove(path).await;
+ }
+ let lease = self
+ .manager
+ .acquire_exact(path, AUTO_LOCK_TIMEOUT, None)
+ .await
+ .map_err(|e| crate::core::Error::internal(format!("lock error: {e}")))?;
+ let result = self.inner.remove(path).await;
+ let release = self.manager.release(&lease).await;
+ Self::merge_operation_and_release(result, release)
+ }
+
+ async fn remove_all(&self, path: &str) -> crate::core::Result<()> {
+ if Self::should_bypass_auto_lock(path) {
+ return self.inner.remove_all(path).await;
+ }
+ let requests = [PathLockRequest {
+ path: path.to_string(),
+ kind: PathLockKind::Tree,
+ }];
+ if self.should_skip_auto_lock(&requests).await? {
+ return self.inner.remove_all(path).await;
+ }
+ let lease = self
+ .manager
+ .acquire_tree(path, AUTO_LOCK_TIMEOUT, None)
+ .await
+ .map_err(|e| crate::core::Error::internal(format!("lock error: {e}")))?;
+ let result = self.inner.remove_all(path).await;
+ let release = self.manager.release(&lease).await;
+ Self::merge_operation_and_release(result, release)
+ }
+
+ async fn read(&self, path: &str, offset: u64, size: u64) -> crate::core::Result<Vec<u8>> {
+ self.inner.read(path, offset, size).await
+ }
+
+ async fn write(
+ &self,
+ path: &str,
+ data: &[u8],
+ offset: u64,
+ flags: WriteFlag,
+ ) -> crate::core::Result<u64> {
+ if Self::should_bypass_auto_lock(path) || self.encryption_handles_pathlock(path).await {
+ return self.inner.write(path, data, offset, flags).await;
+ }
+ let requests = [PathLockRequest {
+ path: path.to_string(),
+ kind: PathLockKind::Exact,
+ }];
+ if self.should_skip_auto_lock(&requests).await? {
+ return self.inner.write(path, data, offset, flags).await;
+ }
+ let lease = self
+ .manager
+ .acquire_exact(path, AUTO_LOCK_TIMEOUT, None)
+ .await
+ .map_err(|e| crate::core::Error::internal(format!("lock error: {e}")))?;
+ let result = self.inner.write(path, data, offset, flags).await;
+ let release = self.manager.release(&lease).await;
+ Self::merge_operation_and_release(result, release)
+ }
+
+ async fn read_dir(&self, path: &str) -> crate::core::Result<Vec<FileInfo>> {
+ self.inner.read_dir(path).await
+ }
+
+ async fn stat(&self, path: &str) -> crate::core::Result<FileInfo> {
+ self.inner.stat(path).await
+ }
+
+ async fn rename(&self, old_path: &str, new_path: &str) -> crate::core::Result<()> {
+ if Self::should_bypass_auto_lock(old_path) || Self::should_bypass_auto_lock(new_path) {
+ return self.inner.rename(old_path, new_path).await;
+ }
+
+ // Determine if source is a directory.
+ let src_is_dir = self
+ .inner
+ .stat(old_path)
+ .await
+ .map(|info| info.is_dir)
+ .unwrap_or(false);
+
+ let requests: Vec<PathLockRequest> = if src_is_dir {
+ vec![
+ PathLockRequest {
+ path: old_path.to_string(),
+ kind: PathLockKind::Tree,
+ },
+ PathLockRequest {
+ path: new_path.to_string(),
+ kind: PathLockKind::Exact,
+ },
+ ]
+ } else {
+ vec![
+ PathLockRequest {
+ path: old_path.to_string(),
+ kind: PathLockKind::Exact,
+ },
+ PathLockRequest {
+ path: new_path.to_string(),
+ kind: PathLockKind::Exact,
+ },
+ ]
+ };
+
+ if self.should_skip_auto_lock(&requests).await? {
+ return self.inner.rename(old_path, new_path).await;
+ }
+
+ let lease = self
+ .manager
+ .acquire_batch(&requests, AUTO_LOCK_TIMEOUT, None)
+ .await
+ .map_err(|e| crate::core::Error::internal(format!("lock error: {e}")))?;
+ let result = self.inner.rename(old_path, new_path).await;
+ let release = self.manager.release(&lease).await;
+ Self::merge_operation_and_release(result, release)
+ }
+
+ async fn replace(&self, src_path: &str, dst_path: &str) -> crate::core::Result<()> {
+ if Self::should_bypass_auto_lock(src_path) || Self::should_bypass_auto_lock(dst_path) {
+ return self.inner.replace(src_path, dst_path).await;
+ }
+
+ let requests = vec![
+ PathLockRequest {
+ path: src_path.to_string(),
+ kind: PathLockKind::Exact,
+ },
+ PathLockRequest {
+ path: dst_path.to_string(),
+ kind: PathLockKind::Exact,
+ },
+ ];
+ if self.should_skip_auto_lock(&requests).await? {
+ return self.inner.replace(src_path, dst_path).await;
+ }
+ let lease = self
+ .manager
+ .acquire_batch(&requests, AUTO_LOCK_TIMEOUT, None)
+ .await
+ .map_err(|e| crate::core::Error::internal(format!("lock error: {e}")))?;
+ let result = self.inner.replace(src_path, dst_path).await;
+ let release = self.manager.release(&lease).await;
+ Self::merge_operation_and_release(result, release)
+ }
+
+ async fn chmod(&self, path: &str, mode: u32) -> crate::core::Result<()> {
+ self.inner.chmod(path, mode).await
+ }
+
+ async fn truncate(&self, path: &str, size: u64) -> crate::core::Result<()> {
+ if Self::should_bypass_auto_lock(path) || self.encryption_handles_pathlock(path).await {
+ return self.inner.truncate(path, size).await;
+ }
+ let requests = [PathLockRequest {
+ path: path.to_string(),
+ kind: PathLockKind::Exact,
+ }];
+ if self.should_skip_auto_lock(&requests).await? {
+ return self.inner.truncate(path, size).await;
+ }
+ let lease = self
+ .manager
+ .acquire_exact(path, AUTO_LOCK_TIMEOUT, None)
+ .await
+ .map_err(|e| crate::core::Error::internal(format!("lock error: {e}")))?;
+ let result = self.inner.truncate(path, size).await;
+ let release = self.manager.release(&lease).await;
+ Self::merge_operation_and_release(result, release)
+ }
+
+ async fn grep(
+ &self,
+ path: &str,
+ pattern: &str,
+ recursive: bool,
+ case_insensitive: bool,
+ node_limit: Option<usize>,
+ exclude_path: Option<&str>,
+ level_limit: Option<usize>,
+ ) -> crate::core::Result<GrepResult> {
+ self.inner
+ .grep(
+ path,
+ pattern,
+ recursive,
+ case_insensitive,
+ node_limit,
+ exclude_path,
+ level_limit,
+ )
+ .await
+ }
+
+ async fn tree_directory(
+ &self,
+ path: &str,
+ show_hidden: bool,
+ node_limit: Option<usize>,
+ level_limit: Option<usize>,
+ ) -> crate::core::Result<Vec<TreeEntry>> {
+ self.inner
+ .tree_directory(path, show_hidden, node_limit, level_limit)
+ .await
+ }
+
+ async fn glob_directory(
+ &self,
+ path: &str,
+ pattern: &str,
+ show_hidden: bool,
+ page_size: Option<usize>,
+ level_limit: Option<usize>,
+ continuation_token: Option<String>,
+ ) -> crate::core::Result<GlobPage> {
+ self.inner
+ .glob_directory(
+ path,
+ pattern,
+ show_hidden,
+ page_size,
+ level_limit,
+ continuation_token,
+ )
+ .await
+ }
+
+ async fn ensure_parent_dirs(&self, path: &str, mode: u32) -> crate::core::Result<()> {
+ self.inner.ensure_parent_dirs(path, mode).await
+ }
+}
diff --git a/crates/ragfs/src/multibackend/factory.rs b/crates/ragfs/src/multibackend/factory.rs
index 0ac98d581..0f657d850 100644
--- a/crates/ragfs/src/multibackend/factory.rs
+++ b/crates/ragfs/src/multibackend/factory.rs
@@ -16,7 +16,7 @@ use crate::multibackend::config::{
item_params_to_config_values, sync_mode_from_config, validate_backup_excludes,
validate_primary_encryption_flags, validate_redirect_targets,
};
-use crate::multibackend::meta::MountRootFsContextResolver;
+use crate::multibackend::meta::RelativePathFsContextResolver;
use crate::multibackend::types::MultiBackendBuildContext;
use crate::shape::validate::ensure_backend_shape;
@@ -85,6 +85,8 @@ pub async fn build_multi_write_fs(
build_ctx
.enc_provider_type
.expect("global encryption validated before building primary backend"),
+ build_ctx.pathlock_manager.clone(),
+ build_ctx.backend_prefix.clone(),
))
} else {
primary_raw.clone()
@@ -146,6 +148,8 @@ pub async fn build_multi_write_fs(
build_ctx
.enc_provider_type
.expect("global encryption validated before building backup backend"),
+ build_ctx.pathlock_manager.clone(),
+ build_ctx.backend_prefix.clone(),
))
} else {
backup_raw
@@ -176,8 +180,6 @@ pub async fn build_multi_write_fs(
.retry_backoff_base_ms(bc.retry_backoff_base_ms.unwrap_or(1_000))
.max_retry_per_round(bc.retry_max_retries_per_round.unwrap_or(3))
.quarantine_after_failures(bc.retry_quarantine_after_failures.unwrap_or(9))
- .ctx_resolver(Arc::new(MountRootFsContextResolver::new(
- &config.mount_path,
- )))
+ .ctx_resolver(Arc::new(RelativePathFsContextResolver))
.build()
}
diff --git a/crates/ragfs/src/multibackend/meta.rs b/crates/ragfs/src/multibackend/meta.rs
index d63766170..457722cd8 100644
--- a/crates/ragfs/src/multibackend/meta.rs
+++ b/crates/ragfs/src/multibackend/meta.rs
@@ -45,44 +45,13 @@ impl FsContextResolver for DefaultFsContextResolver {
}
}
-/// Resolver that extracts `account_id` from paths under one concrete mount root.
-pub struct MountRootFsContextResolver {
- mount_root: String,
-}
-
-impl MountRootFsContextResolver {
- /// Create a resolver for one normalized mount root such as `/local` or `/s3`.
- pub fn new(mount_root: &str) -> Self {
- let mut normalized = mount_root.trim_end_matches('/').to_string();
- if normalized.is_empty() {
- normalized = "/".to_string();
- } else if !normalized.starts_with('/') {
- normalized = format!("/{normalized}");
- }
- Self {
- mount_root: normalized,
- }
- }
-}
+/// Resolver that extracts `account_id` from mount-relative paths such as `/{account_id}/...`.
+pub struct RelativePathFsContextResolver;
-impl FsContextResolver for MountRootFsContextResolver {
+impl FsContextResolver for RelativePathFsContextResolver {
fn resolve(&self, path: &str) -> Result<FsContext> {
- let normalized = if path.starts_with('/') {
- path.to_string()
- } else {
- format!("/{path}")
- };
- let suffix = if self.mount_root == "/" {
- normalized.trim_start_matches('/')
- } else {
- normalized
- .strip_prefix(&self.mount_root)
- .and_then(|suffix| suffix.strip_prefix('/'))
- .ok_or_else(|| {
- Error::internal(format!("cannot resolve FsContext from path: {path}"))
- })?
- };
- let account_id = suffix.split('/').next().unwrap_or_default();
+ let normalized = path.trim_start_matches('/');
+ let account_id = normalized.split('/').next().unwrap_or_default();
if account_id.is_empty() {
return Err(Error::internal(format!(
"cannot resolve FsContext from path: {path}"
@@ -175,12 +144,12 @@ impl MetaStateStore {
Arc::new(FsContextInner::new("_system".to_string()))
}
- /// - root directory using `_system` context
+ /// Build the effective context for metadata access.
fn effective_meta_ctx(dir: &str, ctx: &FsContext) -> FsContext {
if dir == "/" {
- Self::system_ctx()
+ Arc::new(Self::system_ctx().with_auto_pathlock_disabled())
} else {
- ctx.clone()
+ Arc::new(ctx.with_auto_pathlock_disabled())
}
}
@@ -563,15 +532,6 @@ mod tests {
assert!(resolver.resolve("/invalid/path").is_err());
}
- #[test]
- fn test_mount_root_resolver_extracts_account_from_non_local_path() {
- let resolver = MountRootFsContextResolver::new("/s3");
- let ctx = resolver.resolve("/s3/acct-1/resources/file.txt").unwrap();
- assert_eq!(ctx.account_id(), "acct-1");
- assert!(resolver
- .resolve("/local/acct-1/resources/file.txt")
- .is_err());
- }
#[tokio::test]
async fn test_invalid_sync_log_json_returns_error() {
diff --git a/crates/ragfs/src/multibackend/types.rs b/crates/ragfs/src/multibackend/types.rs
index 8e097ee4f..78bb71d66 100644
--- a/crates/ragfs/src/multibackend/types.rs
+++ b/crates/ragfs/src/multibackend/types.rs
@@ -1,12 +1,20 @@
//! Shared build-time types for multi-backend assembly.
+use std::sync::Arc;
+
+use crate::lock::PathLockManager;
+
/// Encryption context used while assembling one multi-backend mount.
-#[derive(Clone, Copy)]
+#[derive(Clone)]
pub struct MultiBackendBuildContext {
/// Global root key, if server-side encryption is enabled.
pub enc_root_key: Option<[u8; 32]>,
/// Global provider type, if server-side encryption is enabled.
pub enc_provider_type: Option<u8>,
+ /// Shared manager used by encrypted backends for dual-path locking.
+ pub pathlock_manager: Arc<PathLockManager>,
+ /// Mount prefix used to restore manager-visible backend paths.
+ pub backend_prefix: String,
}
impl MultiBackendBuildContext {
diff --git a/crates/ragfs/src/plugins/kvfs/mod.rs b/crates/ragfs/src/plugins/kvfs/mod.rs
index e2b1775b0..85be8ed6e 100644
--- a/crates/ragfs/src/plugins/kvfs/mod.rs
+++ b/crates/ragfs/src/plugins/kvfs/mod.rs
@@ -193,6 +193,9 @@ impl FileSystem for KVFileSystem {
WriteFlag::Create | WriteFlag::Truncate => {
entry.value = data.to_vec();
}
+ WriteFlag::CreateNew => {
+ return Err(Error::AlreadyExists(key));
+ }
WriteFlag::Append => {
entry.value.extend_from_slice(data);
}
@@ -211,7 +214,7 @@ impl FileSystem for KVFileSystem {
Ok(data.len() as u64)
}
None => {
- if matches!(flags, WriteFlag::Create) {
+ if matches!(flags, WriteFlag::Create | WriteFlag::CreateNew) {
store.insert(key, KVEntry::new(data.to_vec()));
Ok(data.len() as u64)
} else {
@@ -221,6 +224,38 @@ impl FileSystem for KVFileSystem {
}
}
+ async fn compare_and_write(
+ &self,
+ path: &str,
+ expected: &[u8],
+ new_data: &[u8],
+ ) -> Result<bool> {
+ let key = Self::path_to_key(path);
+ let mut store = self.store.write().await;
+
+ match store.get_mut(&key) {
+ Some(entry) if entry.value.as_slice() == expected => {
+ entry.value = new_data.to_vec();
+ entry.touch();
+ Ok(true)
+ }
+ _ => Ok(false),
+ }
+ }
+
+ async fn compare_and_remove(&self, path: &str, expected: &[u8]) -> Result<bool> {
+ let key = Self::path_to_key(path);
+ let mut store = self.store.write().await;
+
+ match store.get(&key) {
+ Some(entry) if entry.value.as_slice() == expected => {
+ store.remove(&key);
+ Ok(true)
+ }
+ _ => Ok(false),
+ }
+ }
+
async fn read_dir(&self, path: &str) -> Result<Vec<FileInfo>> {
let key = Self::path_to_key(path);
let store = self.store.read().await;
diff --git a/crates/ragfs/src/plugins/localfs/mod.rs b/crates/ragfs/src/plugins/localfs/mod.rs
index af1e97740..bb71063d2 100644
--- a/crates/ragfs/src/plugins/localfs/mod.rs
+++ b/crates/ragfs/src/plugins/localfs/mod.rs
@@ -93,6 +93,148 @@ impl LocalFileSystem {
}
}
+ /// Return whether an open file still identifies the file currently stored at `path`.
+ fn open_file_matches_path(file: &fs::File, path: &Path) -> Result<bool> {
+ let open_metadata = file
+ .metadata()
+ .map_err(|e| Error::plugin(format!("failed to stat open CAS file: {}", e)))?;
+ let path_metadata = match fs::metadata(path) {
+ Ok(metadata) => metadata,
+ Err(e) if e.kind() == std::io::ErrorKind::NotFound => return Ok(false),
+ Err(e) => {
+ return Err(Error::plugin(format!(
+ "failed to stat CAS path '{}': {}",
+ path.display(),
+ e
+ )));
+ }
+ };
+
+ #[cfg(unix)]
+ {
+ use std::os::unix::fs::MetadataExt;
+ Ok(open_metadata.dev() == path_metadata.dev()
+ && open_metadata.ino() == path_metadata.ino())
+ }
+ #[cfg(windows)]
+ {
+ use std::os::windows::fs::MetadataExt;
+ Ok(open_metadata.volume_serial_number() == path_metadata.volume_serial_number()
+ && open_metadata.file_index() == path_metadata.file_index())
+ }
+ #[cfg(not(any(unix, windows)))]
+ {
+ let _ = (open_metadata, path_metadata);
+ Err(Error::invalid_operation(
+ "CAS file identity checks are unsupported on this platform",
+ ))
+ }
+ }
+
+ /// Replace local file content only when the locked file content matches `expected`.
+ fn compare_and_write_locked(
+ local_path: PathBuf,
+ expected: Vec<u8>,
+ new_data: Vec<u8>,
+ ) -> Result<bool> {
+ use std::io::{Read, Seek, SeekFrom, Write};
+
+ let file = fs::OpenOptions::new()
+ .read(true)
+ .write(true)
+ .open(&local_path)
+ .map_err(|e| {
+ if e.kind() == std::io::ErrorKind::NotFound {
+ Error::NotFound(local_path.to_string_lossy().to_string())
+ } else {
+ Error::plugin(format!("failed to open file for compare_and_write: {}", e))
+ }
+ });
+ let file = match file {
+ Ok(file) => file,
+ Err(Error::NotFound(_)) => return Ok(false),
+ Err(e) => return Err(e),
+ };
+ let mut lock = filelocks::LockOptions::new()
+ .backend(filelocks::LockBackend::Fcntl)
+ .lock(
+ file,
+ filelocks::LockKind::Exclusive,
+ filelocks::LockMode::NonBlocking,
+ )
+ .map_err(|e| Error::plugin(format!("failed to lock for compare_and_write: {}", e)))?;
+ let file = lock.file_mut();
+ if !Self::open_file_matches_path(&file, &local_path)? {
+ return Ok(false);
+ }
+
+ let mut current = Vec::new();
+ file.seek(SeekFrom::Start(0))
+ .map_err(|e| Error::plugin(format!("failed to seek for compare_and_write: {}", e)))?;
+ file.read_to_end(&mut current)
+ .map_err(|e| Error::plugin(format!("failed to read for compare_and_write: {}", e)))?;
+ if current != expected {
+ return Ok(false);
+ }
+
+ file.set_len(0)
+ .map_err(|e| Error::plugin(format!("failed to truncate for compare_and_write: {}", e)))?;
+ file.seek(SeekFrom::Start(0))
+ .map_err(|e| Error::plugin(format!("failed to rewind for compare_and_write: {}", e)))?;
+ file.write_all(&new_data)
+ .map_err(|e| Error::plugin(format!("failed to write for compare_and_write: {}", e)))?;
+ file.sync_data()
+ .map_err(|e| Error::plugin(format!("failed to sync for compare_and_write: {}", e)))?;
+ Ok(true)
+ }
+
+ /// Remove a local file only when the locked file content matches `expected`.
+ fn compare_and_remove_locked(local_path: PathBuf, expected: Vec<u8>) -> Result<bool> {
+ use std::io::{Read, Seek, SeekFrom};
+
+ let file = fs::OpenOptions::new()
+ .read(true)
+ .write(true)
+ .open(&local_path)
+ .map_err(|e| {
+ if e.kind() == std::io::ErrorKind::NotFound {
+ Error::NotFound(local_path.to_string_lossy().to_string())
+ } else {
+ Error::plugin(format!("failed to open file for compare_and_remove: {}", e))
+ }
+ });
+ let file = match file {
+ Ok(file) => file,
+ Err(Error::NotFound(_)) => return Ok(false),
+ Err(e) => return Err(e),
+ };
+ let mut lock = filelocks::LockOptions::new()
+ .backend(filelocks::LockBackend::Fcntl)
+ .lock(
+ file,
+ filelocks::LockKind::Exclusive,
+ filelocks::LockMode::NonBlocking,
+ )
+ .map_err(|e| Error::plugin(format!("failed to lock for compare_and_remove: {}", e)))?;
+ let file = lock.file_mut();
+ if !Self::open_file_matches_path(&file, &local_path)? {
+ return Ok(false);
+ }
+
+ let mut current = Vec::new();
+ file.seek(SeekFrom::Start(0))
+ .map_err(|e| Error::plugin(format!("failed to seek for compare_and_remove: {}", e)))?;
+ file.read_to_end(&mut current)
+ .map_err(|e| Error::plugin(format!("failed to read for compare_and_remove: {}", e)))?;
+ if current != expected {
+ return Ok(false);
+ }
+
+ fs::remove_file(&local_path)
+ .map_err(|e| Error::plugin(format!("failed to remove for compare_and_remove: {}", e)))?;
+ Ok(true)
+ }
+
/// Run blocking local filesystem work on a dedicated thread.
async fn run_blocking_fs<T, F>(job: F) -> Result<T>
where
@@ -814,6 +956,9 @@ impl FileSystem for LocalFileSystem {
WriteFlag::Create => {
options.write(true).create(true).truncate(true);
}
+ WriteFlag::CreateNew => {
+ options.write(true).create_new(true);
+ }
WriteFlag::Append => {
options.append(true);
}
@@ -842,6 +987,29 @@ impl FileSystem for LocalFileSystem {
Ok(data.len() as u64)
}
+ /// Atomically replace a local file when its current content exactly matches `expected`.
+ async fn compare_and_write(
+ &self,
+ path: &str,
+ expected: &[u8],
+ new_data: &[u8],
+ ) -> Result<bool> {
+ let local_path = self.resolve_path(path)?;
+ let expected = expected.to_vec();
+ let new_data = new_data.to_vec();
+ Self::run_blocking_fs(move || {
+ Self::compare_and_write_locked(local_path, expected, new_data)
+ })
+ .await
+ }
+
+ /// Atomically remove a local file when its current content exactly matches `expected`.
+ async fn compare_and_remove(&self, path: &str, expected: &[u8]) -> Result<bool> {
+ let local_path = self.resolve_path(path)?;
+ let expected = expected.to_vec();
+ Self::run_blocking_fs(move || Self::compare_and_remove_locked(local_path, expected)).await
+ }
+
async fn read_dir(&self, path: &str) -> Result<Vec<FileInfo>> {
let local_path = self.resolve_path(path)?;
let path = path.to_string();
diff --git a/crates/ragfs/src/plugins/memfs/mod.rs b/crates/ragfs/src/plugins/memfs/mod.rs
index af85f9c19..bdec5a9e8 100644
--- a/crates/ragfs/src/plugins/memfs/mod.rs
+++ b/crates/ragfs/src/plugins/memfs/mod.rs
@@ -280,6 +280,9 @@ impl FileSystem for MemFileSystem {
WriteFlag::Create | WriteFlag::Truncate => {
entry.data = data.to_vec();
}
+ WriteFlag::CreateNew => {
+ return Err(Error::AlreadyExists(normalized));
+ }
WriteFlag::Append => {
entry.data.extend_from_slice(data);
}
@@ -299,8 +302,8 @@ impl FileSystem for MemFileSystem {
Ok(data.len() as u64)
}
None => {
- // Create file if Create flag is set
- if matches!(flags, WriteFlag::Create) {
+ // Create file if Create or CreateNew flag is set
+ if matches!(flags, WriteFlag::Create | WriteFlag::CreateNew) {
// Check parent exists
if let Some(parent) = Self::parent_path(&normalized) {
match entries.get(&parent) {
@@ -321,6 +324,39 @@ impl FileSystem for MemFileSystem {
}
}
+ /// Atomically replace a memory file when its content matches `expected`.
+ async fn compare_and_write(
+ &self,
+ path: &str,
+ expected: &[u8],
+ new_data: &[u8],
+ ) -> Result<bool> {
+ let normalized = Self::normalize_path(path);
+ let mut entries = self.entries.write().await;
+ let Some(entry) = entries.get_mut(&normalized) else {
+ return Ok(false);
+ };
+ if entry.is_dir || entry.data != expected {
+ return Ok(false);
+ }
+ entry.data = new_data.to_vec();
+ entry.touch();
+ Ok(true)
+ }
+
+ /// Atomically remove a memory file when its content matches `expected`.
+ async fn compare_and_remove(&self, path: &str, expected: &[u8]) -> Result<bool> {
+ let normalized = Self::normalize_path(path);
+ let mut entries = self.entries.write().await;
+ let matches = entries
+ .get(&normalized)
+ .is_some_and(|entry| !entry.is_dir && entry.data == expected);
+ if matches {
+ entries.remove(&normalized);
+ }
+ Ok(matches)
+ }
+
async fn read_dir(&self, path: &str) -> Result<Vec<FileInfo>> {
let normalized = Self::normalize_path(path);
let entries = self.entries.read().await;
diff --git a/crates/ragfs/src/plugins/s3fs/client.rs b/crates/ragfs/src/plugins/s3fs/client.rs
index dddda4593..e37b8161e 100644
--- a/crates/ragfs/src/plugins/s3fs/client.rs
+++ b/crates/ragfs/src/plugins/s3fs/client.rs
@@ -110,6 +110,30 @@ where
}
}
+/// Return true when an S3 SDK service error represents a failed conditional request.
+fn is_s3_conditional_failure<E, R>(sdk_err: &SdkError<E, R>) -> bool
+where
+ E: ProvideErrorMetadata,
+ R: 'static,
+{
+ use std::any::Any;
+
+ let SdkError::ServiceError(service_err) = sdk_err else {
+ return false;
+ };
+
+ if matches!(
+ service_err.err().code(),
+ Some("PreconditionFailed" | "ConditionalRequestConflict")
+ ) {
+ return true;
+ }
+
+ (service_err.raw() as &dyn Any)
+ .downcast_ref::<HttpResponse>()
+ .is_some_and(|response| matches!(response.status().as_u16(), 409 | 412))
+}
+
fn format_generic_s3_error(
op: &str,
bucket: &str,
@@ -486,6 +510,46 @@ impl S3Client {
Ok(bytes.to_vec())
}
+ /// Get an object's contents and ETag for conditional updates.
+ pub async fn get_object_with_etag(&self, key: &str) -> Result<Option<(Vec<u8>, String)>> {
+ let resp = match self
+ .client
+ .get_object()
+ .bucket(&self.bucket)
+ .key(key)
+ .send()
+ .await
+ {
+ Ok(resp) => resp,
+ Err(sdk_err) => {
+ let service_err = sdk_err.into_service_error();
+ if service_err.is_no_such_key() {
+ return Ok(None);
+ }
+ return Err(format_s3_service_error(
+ "GetObjectWithEtag",
+ &format!("bucket={} key={}", self.bucket, key),
+ &service_err,
+ ));
+ }
+ };
+
+ let etag = resp.e_tag().ok_or_else(|| {
+ Error::internal(format!(
+ "S3 GetObjectWithEtag missing ETag: bucket={} key={key}",
+ self.bucket
+ ))
+ })?.to_string();
+
+ let bytes = resp
+ .body
+ .collect()
+ .await
+ .map_err(|e| format_generic_s3_error("ReadBody", &self.bucket, key, e))?;
+
+ Ok(Some((bytes.to_vec(), etag)))
+ }
+
/// Get an object's contents with range request
pub async fn get_object_range(&self, key: &str, offset: u64, size: u64) -> Result<Vec<u8>> {
let range = if size == 0 {
@@ -552,6 +616,72 @@ impl S3Client {
Ok(())
}
+ /// Upload an object only when the key does not already exist.
+ pub async fn put_object_create_new(&self, key: &str, data: Vec<u8>) -> Result<()> {
+ let mut request = self
+ .client
+ .put_object()
+ .bucket(&self.bucket)
+ .key(key)
+ .if_none_match("*")
+ .body(ByteStream::from(data));
+
+ if self.auto_detect_content_type {
+ if let Some(content_type) = detect_content_type_for_key(key) {
+ request = request.content_type(content_type);
+ }
+ }
+
+ request.send().await.map_err(|e| {
+ if is_s3_conditional_failure(&e) {
+ Error::already_exists(key)
+ } else {
+ format_sdk_s3_error(
+ "PutObjectCreateNew",
+ &format!("bucket={} key={key}", self.bucket),
+ &e,
+ )
+ }
+ })?;
+
+ Ok(())
+ }
+
+ /// Upload an object only when its ETag still matches `etag`.
+ pub async fn put_object_if_match(&self, key: &str, data: Vec<u8>, etag: &str) -> Result<bool> {
+ let mut request = self
+ .client
+ .put_object()
+ .bucket(&self.bucket)
+ .key(key)
+ .if_match(etag)
+ .body(ByteStream::from(data));
+
+ if self.auto_detect_content_type {
+ if let Some(content_type) = detect_content_type_for_key(key) {
+ request = request.content_type(content_type);
+ }
+ }
+
+ request.send().await.map_err(|e| {
+ if is_s3_conditional_failure(&e) {
+ Error::AlreadyExists(key.to_string())
+ } else {
+ format_sdk_s3_error(
+ "PutObjectIfMatch",
+ &format!("bucket={} key={key}", self.bucket),
+ &e,
+ )
+ }
+ }).map(|_| true).or_else(|e| {
+ if matches!(e, Error::AlreadyExists(_)) {
+ Ok(false)
+ } else {
+ Err(e)
+ }
+ })
+ }
+
/// Delete a single object
pub async fn delete_object(&self, key: &str) -> Result<()> {
self.client
@@ -571,6 +701,36 @@ impl S3Client {
Ok(())
}
+ /// Delete a single object only when its ETag still matches `etag`.
+ pub async fn delete_object_if_match(&self, key: &str, etag: &str) -> Result<bool> {
+ self.client
+ .delete_object()
+ .bucket(&self.bucket)
+ .key(key)
+ .if_match(etag)
+ .send()
+ .await
+ .map_err(|e| {
+ if is_s3_conditional_failure(&e) {
+ Error::AlreadyExists(key.to_string())
+ } else {
+ format_sdk_s3_error(
+ "DeleteObjectIfMatch",
+ &format!("bucket={} key={key}", self.bucket),
+ &e,
+ )
+ }
+ })
+ .map(|_| true)
+ .or_else(|e| {
+ if matches!(e, Error::AlreadyExists(_)) {
+ Ok(false)
+ } else {
+ Err(e)
+ }
+ })
+ }
+
/// Batch delete objects (up to 1000 per call)
/// If disable_batch_delete is true, use sequential single-object deletes
/// for S3-compatible services (e.g., Alibaba Cloud OSS) that require
diff --git a/crates/ragfs/src/plugins/s3fs/mod.rs b/crates/ragfs/src/plugins/s3fs/mod.rs
index 38e378094..d49334965 100644
--- a/crates/ragfs/src/plugins/s3fs/mod.rs
+++ b/crates/ragfs/src/plugins/s3fs/mod.rs
@@ -29,7 +29,7 @@ use regex::Regex;
use std::sync::atomic::{AtomicUsize, Ordering};
use crate::core::filesystem::{relative_depth, relative_match_file, sort_directory_entries};
-use crate::core::glob::{PreparedGlob, validate_pattern};
+use crate::core::glob::PreparedGlob;
use crate::core::{
ConfigParameter, Error, FileInfo, FileSystem, GlobEntry, GlobPage, GrepMatch, GrepResult,
PluginConfig, Result, ServicePlugin, TreeEntry, WriteFlag,
@@ -573,12 +573,19 @@ impl FileSystem for S3FileSystem {
}
}
- async fn write(&self, path: &str, data: &[u8], _offset: u64, _flags: WriteFlag) -> Result<u64> {
+ async fn write(&self, path: &str, data: &[u8], _offset: u64, flags: WriteFlag) -> Result<u64> {
let normalized = Self::normalize_path(path);
let key = self.client.build_key(&normalized);
- // S3 always replaces the full object
- self.client.put_object(&key, data.to_vec()).await?;
+ match flags {
+ WriteFlag::CreateNew => {
+ self.client.put_object_create_new(&key, data.to_vec()).await?;
+ }
+ _ => {
+ // S3 always replaces the full object for non-exclusive writes.
+ self.client.put_object(&key, data.to_vec()).await?;
+ }
+ }
// Invalidate caches
self.dir_cache.invalidate_parent(&normalized).await;
@@ -587,6 +594,48 @@ impl FileSystem for S3FileSystem {
Ok(data.len() as u64)
}
+ async fn compare_and_write(
+ &self,
+ path: &str,
+ expected: &[u8],
+ new_data: &[u8],
+ ) -> Result<bool> {
+ let normalized = Self::normalize_path(path);
+ let key = self.client.build_key(&normalized);
+ let Some((current, etag)) = self.client.get_object_with_etag(&key).await? else {
+ return Ok(false);
+ };
+ if current.as_slice() != expected {
+ return Ok(false);
+ }
+ let changed = self
+ .client
+ .put_object_if_match(&key, new_data.to_vec(), &etag)
+ .await?;
+ if changed {
+ self.dir_cache.invalidate_parent(&normalized).await;
+ self.stat_cache.invalidate(&normalized).await;
+ }
+ Ok(changed)
+ }
+
+ async fn compare_and_remove(&self, path: &str, expected: &[u8]) -> Result<bool> {
+ let normalized = Self::normalize_path(path);
+ let key = self.client.build_key(&normalized);
+ let Some((current, etag)) = self.client.get_object_with_etag(&key).await? else {
+ return Ok(false);
+ };
+ if current.as_slice() != expected {
+ return Ok(false);
+ }
+ let changed = self.client.delete_object_if_match(&key, &etag).await?;
+ if changed {
+ self.dir_cache.invalidate_parent(&normalized).await;
+ self.stat_cache.invalidate(&normalized).await;
+ }
+ Ok(changed)
+ }
+
async fn read_dir(&self, path: &str) -> Result<Vec<FileInfo>> {
let normalized = Self::normalize_path(path);
diff --git a/crates/ragfs/src/plugins/sqlfs/backend.rs b/crates/ragfs/src/plugins/sqlfs/backend.rs
index 5fa01efb7..f16314bed 100644
--- a/crates/ragfs/src/plugins/sqlfs/backend.rs
+++ b/crates/ragfs/src/plugins/sqlfs/backend.rs
@@ -46,6 +46,12 @@ pub trait DatabaseBackend: Send + Sync {
/// Update file data
fn update_file(&self, path: &str, data: &[u8]) -> Result<()>;
+ /// Update file data only when the current data equals `expected`.
+ fn compare_and_update_file(&self, path: &str, expected: &[u8], data: &[u8]) -> Result<bool>;
+
+ /// Delete a file only when the current data equals `expected`.
+ fn compare_and_delete_file(&self, path: &str, expected: &[u8]) -> Result<bool>;
+
/// Get file metadata
fn get_metadata(&self, path: &str) -> Result<Option<FileMetadata>>;
@@ -278,6 +284,35 @@ impl DatabaseBackend for SQLiteBackend {
Ok(())
}
+ fn compare_and_update_file(&self, path: &str, expected: &[u8], data: &[u8]) -> Result<bool> {
+ let conn = self
+ .conn
+ .lock()
+ .map_err(|e| Error::internal(e.to_string()))?;
+ let now = chrono::Utc::now().timestamp();
+ let changed = conn
+ .execute(
+ "UPDATE files SET data = ?1, size = ?2, mod_time = ?3 WHERE path = ?4 AND is_dir = 0 AND data = ?5",
+ params![data, data.len() as i64, now, path, expected],
+ )
+ .map_err(|e| Error::internal(format!("conditional update error: {}", e)))?;
+ Ok(changed == 1)
+ }
+
+ fn compare_and_delete_file(&self, path: &str, expected: &[u8]) -> Result<bool> {
+ let conn = self
+ .conn
+ .lock()
+ .map_err(|e| Error::internal(e.to_string()))?;
+ let changed = conn
+ .execute(
+ "DELETE FROM files WHERE path = ?1 AND is_dir = 0 AND data = ?2",
+ params![path, expected],
+ )
+ .map_err(|e| Error::internal(format!("conditional delete error: {}", e)))?;
+ Ok(changed == 1)
+ }
+
fn get_metadata(&self, path: &str) -> Result<Option<FileMetadata>> {
let conn = self
.conn
diff --git a/crates/ragfs/src/plugins/sqlfs/mod.rs b/crates/ragfs/src/plugins/sqlfs/mod.rs
index f990850c8..0ab7bb367 100644
--- a/crates/ragfs/src/plugins/sqlfs/mod.rs
+++ b/crates/ragfs/src/plugins/sqlfs/mod.rs
@@ -110,6 +110,27 @@ impl SQLFileSystem {
let normalized = Self::normalize_path(path);
normalized.rsplit('/').next().unwrap_or("").to_string()
}
+
+ /// Run one synchronous database operation on Tokio's blocking pool.
+ ///
+ /// # Arguments
+ /// * `job` - Blocking database work that uses the SQL backend directly
+ ///
+ /// # Returns
+ /// The operation result converted back into the async SQLFS call path.
+ async fn run_blocking_db<T, F>(&self, job: F) -> Result<T>
+ where
+ T: Send + 'static,
+ F: FnOnce(&dyn DatabaseBackend) -> Result<T> + Send + 'static,
+ {
+ let backend = Arc::clone(&self.backend);
+ tokio::task::spawn_blocking(move || {
+ let backend = backend.blocking_read();
+ job(backend.as_ref())
+ })
+ .await
+ .map_err(|e| Error::internal(format!("sqlfs blocking task join error: {e}")))?
+ }
}
impl Default for SQLFileSystem {
@@ -261,9 +282,11 @@ impl FileSystem for SQLFileSystem {
async fn read(&self, path: &str, offset: u64, size: u64) -> Result<Vec<u8>> {
let normalized = Self::normalize_path(path);
- let backend = self.backend.read().await;
-
- match backend.read_file(&normalized)? {
+ let normalized_for_db = normalized.clone();
+ match self
+ .run_blocking_db(move |backend| backend.read_file(&normalized_for_db))
+ .await?
+ {
Some((is_dir, data)) => {
if is_dir {
return Err(Error::IsADirectory(normalized));
@@ -308,41 +331,87 @@ impl FileSystem for SQLFileSystem {
));
}
- let backend = self.backend.read().await;
+ let normalized_for_db = normalized.clone();
+ let data_owned = data.to_vec();
+ let created_new = self
+ .run_blocking_db(move |backend| {
+ let exists = backend.path_exists(&normalized_for_db)?;
+
+ if exists {
+ // Check if it's a directory
+ if backend.is_directory(&normalized_for_db)? {
+ return Err(Error::IsADirectory(normalized_for_db.clone()));
+ }
- let exists = backend.path_exists(&normalized)?;
+ if matches!(flags, WriteFlag::CreateNew) {
+ return Err(Error::AlreadyExists(normalized_for_db.clone()));
+ }
- if exists {
- // Check if it's a directory
- if backend.is_directory(&normalized)? {
- return Err(Error::IsADirectory(normalized));
- }
+ backend.update_file(&normalized_for_db, &data_owned)?;
+ Ok(false)
+ } else {
+ if !matches!(flags, WriteFlag::Create | WriteFlag::CreateNew) {
+ return Err(Error::not_found(&normalized_for_db));
+ }
- // Update existing file
- backend.update_file(&normalized, data)?;
- } else {
- // Create new file
- if !matches!(flags, WriteFlag::Create) {
- return Err(Error::not_found(&normalized));
- }
+ let parent = backend.parent_path(&normalized_for_db);
+ if parent != "/" && !backend.is_directory(&parent)? {
+ return Err(Error::not_found(&parent));
+ }
- // Check parent exists
- let parent = backend.parent_path(&normalized);
- if parent != "/" {
- if !backend.is_directory(&parent)? {
- return Err(Error::not_found(&parent));
+ backend.create_file(&normalized_for_db, 0o644, &data_owned)?;
+ Ok(true)
}
- }
-
- backend.create_file(&normalized, 0o644, data)?;
+ })
+ .await?;
- // Invalidate parent cache
+ if created_new {
self.cache.invalidate_parent(&normalized).await;
}
Ok(data.len() as u64)
}
+ async fn compare_and_write(
+ &self,
+ path: &str,
+ expected: &[u8],
+ new_data: &[u8],
+ ) -> Result<bool> {
+ let normalized = Self::normalize_path(path);
+ let normalized_for_db = normalized.clone();
+ let expected_owned = expected.to_vec();
+ let new_data_owned = new_data.to_vec();
+ let changed = self
+ .run_blocking_db(move |backend| {
+ backend.compare_and_update_file(
+ &normalized_for_db,
+ &expected_owned,
+ &new_data_owned,
+ )
+ })
+ .await?;
+ if changed {
+ self.cache.invalidate_parent(&normalized).await;
+ }
+ Ok(changed)
+ }
+
+ async fn compare_and_remove(&self, path: &str, expected: &[u8]) -> Result<bool> {
+ let normalized = Self::normalize_path(path);
+ let normalized_for_db = normalized.clone();
+ let expected_owned = expected.to_vec();
+ let changed = self
+ .run_blocking_db(move |backend| {
+ backend.compare_and_delete_file(&normalized_for_db, &expected_owned)
+ })
+ .await?;
+ if changed {
+ self.cache.invalidate_parent(&normalized).await;
+ }
+ Ok(changed)
+ }
+
async fn read_dir(&self, path: &str) -> Result<Vec<FileInfo>> {
let normalized = Self::normalize_path(path);
@@ -351,19 +420,21 @@ impl FileSystem for SQLFileSystem {
return Ok(files);
}
- let backend = self.backend.read().await;
-
- // Check if directory exists
- if !backend.path_exists(&normalized)? {
- return Err(Error::not_found(&normalized));
- }
+ let normalized_for_db = normalized.clone();
+ let list_path = normalized.clone();
+ let entries = self
+ .run_blocking_db(move |backend| {
+ if !backend.path_exists(&normalized_for_db)? {
+ return Err(Error::not_found(&normalized_for_db));
+ }
- if !backend.is_directory(&normalized)? {
- return Err(Error::NotADirectory(normalized));
- }
+ if !backend.is_directory(&normalized_for_db)? {
+ return Err(Error::NotADirectory(normalized_for_db));
+ }
- // List directory
- let entries = backend.list_directory(&normalized)?;
+ backend.list_directory(&list_path)
+ })
+ .await?;
// Convert to FileInfo
let mut files = Vec::new();
@@ -387,9 +458,11 @@ impl FileSystem for SQLFileSystem {
async fn stat(&self, path: &str) -> Result<FileInfo> {
let normalized = Self::normalize_path(path);
- let backend = self.backend.read().await;
-
- match backend.get_metadata(&normalized)? {
+ let normalized_for_db = normalized.clone();
+ match self
+ .run_blocking_db(move |backend| backend.get_metadata(&normalized_for_db))
+ .await?
+ {
Some(meta) => Ok(FileInfo {
name: Self::file_name(&normalized),
size: meta.size as u64,
diff --git a/crates/ragfs/src/shape/probe.rs b/crates/ragfs/src/shape/probe.rs
index 4a098b39e..254c78e40 100644
--- a/crates/ragfs/src/shape/probe.rs
+++ b/crates/ragfs/src/shape/probe.rs
@@ -2,6 +2,7 @@ use std::sync::Arc;
use crate::core::errors::{Error, Result};
use crate::core::filesystem::FileSystem;
+use crate::core::internal_names::is_hidden_runtime_lock_name;
use crate::core::WriteFlag;
use crate::crypto;
use futures::stream::{self, StreamExt};
@@ -9,8 +10,6 @@ use futures::stream::{self, StreamExt};
use super::manifest::{StorageShape, SHAPE_MANIFEST_PATH};
const SYSTEM_ACCOUNT_ID: &[u8] = b"_system";
-const PATH_LOCK_FILE: &str = ".path.ovlock";
-const EXACT_LOCK_FILE_PREFIX: &str = ".exact.ovlock.";
fn normalize_shape_path(path: &str) -> String {
let mut normalized = path.trim().to_string();
@@ -36,7 +35,7 @@ fn is_persistent_task_record_path(path: &str) -> bool {
fn is_path_lock_record_path(path: &str) -> bool {
let name = path.rsplit('/').next().unwrap_or("");
- name == PATH_LOCK_FILE || name.starts_with(EXACT_LOCK_FILE_PREFIX)
+ is_hidden_runtime_lock_name(name)
}
/// Read the raw guard-file bytes from the backend root.
diff --git a/openviking/async_client.py b/openviking/async_client.py
index 065f99093..883a6ac31 100644
--- a/openviking/async_client.py
+++ b/openviking/async_client.py
@@ -109,11 +109,6 @@ class AsyncOpenViking:
await cls._instance.close()
cls._instance = None
- # Also reset lock manager singleton
- from openviking.storage.transaction import reset_lock_manager
-
- reset_lock_manager()
-
# ============= Session methods =============
def session(self, session_id: Optional[str] = None, must_exist: bool = False) -> Session:
diff --git a/openviking/metrics/datasources/observer_state.py b/openviking/metrics/datasources/observer_state.py
index 86544ac87..68613729e 100644
--- a/openviking/metrics/datasources/observer_state.py
+++ b/openviking/metrics/datasources/observer_state.py
@@ -3,11 +3,10 @@
from __future__ import annotations
-import time
from typing import Any
from openviking.metrics.core.base import ReadEnvelope
-from openviking.storage.transaction import get_lock_manager
+from openviking.storage.viking_fs import get_viking_fs
from openviking_cli.utils import run_async
from .base import DomainStatsMetricDataSource, StateMetricDataSource
@@ -62,36 +61,27 @@ class ObserverStateDataSource(DomainStatsMetricDataSource):
class LockStateDataSource(StateMetricDataSource):
"""
- Read lock-manager counters needed by lock-related state collectors.
+ Read lock-manager counters from the pathlock observe snapshot.
- The datasource inspects active lock handles and derives a stale-handle count using the
- current in-process timeout heuristic.
+ The datasource reads the ``pathlock_observe()`` snapshot to derive active,
+ waiting, and stale lock counts.
"""
def read_lock_state(self) -> ReadEnvelope[tuple[int, int, int]]:
"""
- Read active and stale lock counts from the global transaction lock manager.
+ Read active, waiting, and stale lock counts from the pathlock observe snapshot.
Returns:
- A tuple of `(active_locks, waiting_locks, stale_handles)` where waiting locks are
- currently not tracked separately and therefore remain `0`.
+ A tuple of ``(active_locks, waiting_locks, stale_locks_removed)``.
"""
def _read() -> tuple[int, int, int]:
- lock_manager = get_lock_manager()
- handles = lock_manager.get_active_handles()
- active = 0
- stale = 0
- now = time.time()
- for handle in handles.values():
- try:
- active += len(getattr(handle, "locks", []) or [])
- last = getattr(handle, "last_active_at", None)
- if last is not None and (now - float(last)) > 600:
- stale += 1
- except Exception:
- continue
- return active, 0, stale
+ viking_fs = get_viking_fs()
+ snapshot = run_async(viking_fs._async_agfs.pathlock_observe())
+ active = int(snapshot.get("active_locks", 0))
+ waiting = int(snapshot.get("waiting_locks", 0))
+ stale = int(snapshot.get("stale_locks_removed", 0))
+ return active, waiting, stale
return self.safe_read(_read, default=(0, 0, 0))
diff --git a/openviking/parse/image_rewrite.py b/openviking/parse/image_rewrite.py
index 66e8e0878..8f2482cb9 100644
--- a/openviking/parse/image_rewrite.py
+++ b/openviking/parse/image_rewrite.py
@@ -11,15 +11,12 @@ images themselves are stored next to the markdown file referencing them).
import json
import re
from pathlib import Path
-from typing import TYPE_CHECKING, Dict, Optional, Set
+from typing import Any, Dict, Optional, Set
from openviking.server.identity import RequestContext
from openviking.storage.viking_fs import get_viking_fs
from openviking_cli.utils import get_logger
-if TYPE_CHECKING:
- from openviking.storage.transaction.lock_handle import LockHandle
-
logger = get_logger(__name__)
_IMAGE_PATTERN = re.compile(r"!\[([^\]]*)\]\(((?:[^()]|\([^()]*\))+)\)")
@@ -259,7 +256,7 @@ async def _discover_mappings(
async def rewrite_image_uris(
root_uri: str,
ctx: Optional[RequestContext] = None,
- lock_handle: Optional["LockHandle"] = None,
+ lease_ref: Optional[Dict[str, Any]] = None,
) -> Dict[str, int]:
"""Rewrite local image references in markdown files to viking:// URIs.
@@ -277,7 +274,7 @@ async def rewrite_image_uris(
Args:
root_uri: The final VikingFS root URI (e.g. ``viking://resources/doc``)
ctx: Optional request context for permissions
- lock_handle: Optional lock handle held by the caller. When the caller
+ lease_ref: Optional lease reference held by the caller. When the caller
already owns a TREE lock over *root_uri*, forwarding it lets the
cleanup ``rm`` reuse that lock instead of conflicting with it.
@@ -337,12 +334,11 @@ async def rewrite_image_uris(
if rewrite_count > 0:
try:
- # TODO: This must be optimized once pathlock is pushed down into ragfs.
await viking_fs.write_file(
md_uri,
new_content,
ctx=ctx,
- lock_handle=lock_handle,
+ lease_ref=lease_ref,
)
files_processed += 1
references_rewritten += rewrite_count
@@ -354,7 +350,9 @@ async def rewrite_image_uris(
for map_dir in mappings_by_dir:
try:
await viking_fs.rm(
- f"{map_dir}/{IMAGE_MAPPINGS_FILENAME}", ctx=ctx, lock_handle=lock_handle
+ f"{map_dir}/{IMAGE_MAPPINGS_FILENAME}",
+ ctx=ctx,
+ lease_ref=lease_ref,
)
except Exception as e:
logger.warning(
diff --git a/openviking/pyagfs/async_client.py b/openviking/pyagfs/async_client.py
index 3e1fd7457..5182f2b71 100644
--- a/openviking/pyagfs/async_client.py
+++ b/openviking/pyagfs/async_client.py
@@ -253,3 +253,238 @@ class AsyncAGFSClient:
) -> Dict[str, Any]:
"""Retry pending multi-write sync work for a file or directory path."""
return await self.run("system_sync_retry", path, ctx=_fs_ctx_or_default(path, fs_ctx))
+
+ # -- pathlock async wrappers ------------------------------------------------
+
+ async def pathlock_acquire_exact(
+ self,
+ path: str,
+ timeout_secs: float = 0.0,
+ owner_lease_ref: Dict[str, Any] | None = None,
+ *,
+ fs_ctx: Dict[str, str] | None = None,
+ ) -> Dict[str, Any]:
+ """Acquire an exact lock on a single path."""
+ return await self.run(
+ "pathlock_acquire_exact",
+ _fs_ctx_or_default(path, fs_ctx),
+ path,
+ timeout_secs,
+ owner_lease_ref,
+ )
+
+ async def pathlock_acquire_exact_batch(
+ self,
+ paths: list[str],
+ timeout_secs: float = 0.0,
+ owner_lease_ref: Dict[str, Any] | None = None,
+ *,
+ fs_ctx: Dict[str, str] | None = None,
+ ) -> Dict[str, Any]:
+ """Acquire exact locks on multiple paths."""
+ return await self.run(
+ "pathlock_acquire_exact_batch",
+ _fs_ctx_or_default(paths[0] if paths else "/", fs_ctx),
+ paths,
+ timeout_secs,
+ owner_lease_ref,
+ )
+
+ async def pathlock_acquire_tree(
+ self,
+ path: str,
+ timeout_secs: float = 0.0,
+ owner_lease_ref: Dict[str, Any] | None = None,
+ *,
+ fs_ctx: Dict[str, str] | None = None,
+ ) -> Dict[str, Any]:
+ """Acquire a tree lock on a single path."""
+ return await self.run(
+ "pathlock_acquire_tree",
+ _fs_ctx_or_default(path, fs_ctx),
+ path,
+ timeout_secs,
+ owner_lease_ref,
+ )
+
+ async def pathlock_acquire_tree_batch(
+ self,
+ paths: list[str],
+ timeout_secs: float = 0.0,
+ owner_lease_ref: Dict[str, Any] | None = None,
+ *,
+ fs_ctx: Dict[str, str] | None = None,
+ ) -> Dict[str, Any]:
+ """Acquire tree locks on multiple paths."""
+ return await self.run(
+ "pathlock_acquire_tree_batch",
+ _fs_ctx_or_default(paths[0] if paths else "/", fs_ctx),
+ paths,
+ timeout_secs,
+ owner_lease_ref,
+ )
+
+ async def pathlock_acquire_exact_tree_batch(
+ self,
+ exact_paths: list[str],
+ tree_paths: list[str],
+ timeout_secs: float = 0.0,
+ owner_lease_ref: Dict[str, Any] | None = None,
+ *,
+ fs_ctx: Dict[str, str] | None = None,
+ ) -> Dict[str, Any]:
+ """Acquire a mixed batch of exact and tree locks."""
+ first = exact_paths[0] if exact_paths else (tree_paths[0] if tree_paths else "/")
+ return await self.run(
+ "pathlock_acquire_exact_tree_batch",
+ _fs_ctx_or_default(first, fs_ctx),
+ exact_paths,
+ tree_paths,
+ timeout_secs,
+ owner_lease_ref,
+ )
+
+ async def pathlock_acquire_batch(
+ self,
+ requests: list[Dict[str, str]],
+ timeout_secs: float = 0.0,
+ owner_lease_ref: Dict[str, Any] | None = None,
+ *,
+ fs_ctx: Dict[str, str] | None = None,
+ ) -> Dict[str, Any]:
+ """Acquire a batch of locks from a list of request dicts."""
+ if not requests:
+ raise ValueError("pathlock request batch must not be empty")
+ for request in requests:
+ path = request.get("path")
+ if not path or not path.startswith("/"):
+ raise ValueError("pathlock request.path must be an absolute path")
+ if request.get("kind") not in {"exact", "tree"}:
+ raise ValueError("pathlock request.kind must be 'exact' or 'tree'")
+ first = requests[0]["path"]
+ return await self.run(
+ "pathlock_acquire_batch",
+ _fs_ctx_or_default(first, fs_ctx),
+ requests,
+ timeout_secs,
+ owner_lease_ref,
+ )
+
+ async def pathlock_as_borrowed(
+ self,
+ owned_lease_ref: Dict[str, Any],
+ *,
+ fs_ctx: Dict[str, str] | None = None,
+ ) -> Dict[str, Any]:
+ """Create a borrowed view of an owned lease."""
+ return await self.run(
+ "pathlock_as_borrowed",
+ _fs_ctx_or_default("/", fs_ctx),
+ owned_lease_ref,
+ )
+
+ async def pathlock_refresh(
+ self,
+ owned_lease_ref: Dict[str, Any],
+ *,
+ fs_ctx: Dict[str, str] | None = None,
+ ) -> str:
+ """Refresh an owned lease. Returns 'refreshed', 'lost', or 'failed'."""
+ return await self.run(
+ "pathlock_refresh",
+ _fs_ctx_or_default("/", fs_ctx),
+ owned_lease_ref,
+ )
+
+ async def pathlock_release(
+ self,
+ owned_lease_ref: Dict[str, Any],
+ *,
+ fs_ctx: Dict[str, str] | None = None,
+ ) -> None:
+ """Release an owned lease."""
+ await self.run(
+ "pathlock_release",
+ _fs_ctx_or_default("/", fs_ctx),
+ owned_lease_ref,
+ )
+
+ async def pathlock_release_selected(
+ self,
+ owned_lease_ref: Dict[str, Any],
+ lock_paths: list[str],
+ *,
+ fs_ctx: Dict[str, str] | None = None,
+ ) -> None:
+ """Release selected lock paths from an owned lease."""
+ await self.run(
+ "pathlock_release_selected",
+ _fs_ctx_or_default("/", fs_ctx),
+ owned_lease_ref,
+ lock_paths,
+ )
+
+ async def pathlock_to_handoff(
+ self,
+ owned_lease_ref: Dict[str, Any],
+ *,
+ fs_ctx: Dict[str, str] | None = None,
+ ) -> Dict[str, Any]:
+ """Export a handoff ref from an owned lease."""
+ return await self.run(
+ "pathlock_to_handoff",
+ _fs_ctx_or_default("/", fs_ctx),
+ owned_lease_ref,
+ )
+
+ async def pathlock_handoff(
+ self,
+ owned_lease_ref: Dict[str, Any],
+ *,
+ fs_ctx: Dict[str, str] | None = None,
+ ) -> None:
+ """Mark an owned lease as handed off."""
+ await self.run(
+ "pathlock_handoff",
+ _fs_ctx_or_default("/", fs_ctx),
+ owned_lease_ref,
+ )
+
+ async def pathlock_adopt(
+ self,
+ handoff_ref: Dict[str, Any],
+ *,
+ fs_ctx: Dict[str, str] | None = None,
+ ) -> Dict[str, Any]:
+ """Adopt a handoff ref, returning a new owned lease."""
+ return await self.run(
+ "pathlock_adopt",
+ _fs_ctx_or_default("/", fs_ctx),
+ handoff_ref,
+ )
+
+ async def pathlock_is_locked(
+ self,
+ path: str,
+ ignore_stale: bool = True,
+ *,
+ fs_ctx: Dict[str, str] | None = None,
+ ) -> bool:
+ """Check if a path is locked."""
+ return await self.run(
+ "pathlock_is_locked",
+ _fs_ctx_or_default(path, fs_ctx),
+ path,
+ ignore_stale,
+ )
+
+ async def pathlock_observe(
+ self,
+ *,
+ fs_ctx: Dict[str, str] | None = None,
+ ) -> Dict[str, Any]:
+ """Return an observability snapshot of current lock state."""
+ return await self.run(
+ "pathlock_observe",
+ _fs_ctx_or_default("/", fs_ctx),
+ )
diff --git a/openviking/server/api_keys/legacy.py b/openviking/server/api_keys/legacy.py
index d19b1095e..5a1910ee4 100644
--- a/openviking/server/api_keys/legacy.py
+++ b/openviking/server/api_keys/legacy.py
@@ -14,10 +14,10 @@ from argon2 import PasswordHasher
from argon2.exceptions import VerifyMismatchError
from openviking.pyagfs import AGFSAlreadyExistsError, AGFSNotFoundError, AsyncAGFSClient
+from openviking.pyagfs.async_client import fs_ctx_from_agfs_path
from openviking.server.api_keys.models import AccountInfo, UserKeyEntry
from openviking.server.identity import ResolvedIdentity, Role
from openviking.storage.errors import LockAcquisitionError, ResourceBusyError
-from openviking.storage.transaction import LockContext, get_lock_manager
from openviking.storage.viking_fs import VikingFS
from openviking_cli.exceptions import (
AlreadyExistsError,
@@ -383,7 +383,9 @@ class LegacyAPIKeyManager:
await self._save_users_json(account_id)
- async def regenerate_key(self, account_id: str, user_id: str, seed: Optional[str] = None) -> str:
+ async def regenerate_key(
+ self, account_id: str, user_id: str, seed: Optional[str] = None
+ ) -> str:
"""Regenerate a user's API key. Old key is immediately invalidated."""
account = self._accounts.get(account_id)
if account is None:
@@ -635,14 +637,34 @@ class LegacyAPIKeyManager:
except AGFSNotFoundError:
return None
- async def _write_json(self, path: str, data: dict) -> None:
+ @staticmethod
+ def _fs_ctx_with_lease(path: str, lease_ref: object | None) -> Dict[str, str] | None:
+ """Build an AGFS fs_ctx that preserves account_id and an optional lease_ref."""
+ if lease_ref is None:
+ return None
+ ref = None
+ if isinstance(lease_ref, dict):
+ ref = lease_ref.get("lease_ref")
+ else:
+ ref = getattr(lease_ref, "lease_ref", None) or getattr(lease_ref, "id", None)
+ if not isinstance(ref, str) or not ref:
+ return None
+ fs_ctx = fs_ctx_from_agfs_path(path)
+ fs_ctx["lease_ref"] = ref
+ return fs_ctx
+
+ async def _write_json(self, path: str, data: dict, lease_ref: object | None = None) -> None:
"""Write a JSON file to AGFS with encryption support."""
content = json.dumps(data, ensure_ascii=False, indent=2)
if isinstance(content, str):
content = content.encode("utf-8")
await self._ensure_parent_dirs_async(path)
- await self._async_agfs.write(path, content)
+ await self._async_agfs.write(
+ path,
+ content,
+ fs_ctx=self._fs_ctx_with_lease(path, lease_ref),
+ )
async def _ensure_parent_dirs_async(self, path: str) -> None:
"""Recursively create all parent directories for a file path."""
@@ -654,37 +676,38 @@ class LegacyAPIKeyManager:
async def _save_accounts_json(self) -> None:
"""Persist the global accounts list."""
try:
- async with LockContext(
- get_lock_manager(), [ACCOUNTS_PATH], lock_mode="exact", timeout=10.0
- ):
- data = {
- "accounts": {
- aid: {"created_at": info.created_at}
- for aid, info in self._accounts.items()
- }
- }
- await self._write_json(ACCOUNTS_PATH, data)
+ lease = await self._async_agfs.pathlock_acquire_exact(ACCOUNTS_PATH, timeout_secs=10.0)
except LockAcquisitionError as exc:
raise ResourceBusyError(
"Another account operation is in progress. Please retry.",
uri=ACCOUNTS_PATH,
conflict_type="account_registry_busy",
) from exc
+ try:
+ data = {
+ "accounts": {
+ aid: {"created_at": info.created_at} for aid, info in self._accounts.items()
+ }
+ }
+ await self._write_json(ACCOUNTS_PATH, data, lease_ref=lease)
+ finally:
+ await self._async_agfs.pathlock_release(lease)
async def _save_users_json(self, account_id: str) -> None:
"""Persist a single account's user registry."""
path = USERS_PATH_TEMPLATE.format(account_id=account_id)
try:
- async with LockContext(
- get_lock_manager(), [path], lock_mode="exact", timeout=10.0
- ):
- account = self._accounts.get(account_id)
- if account is None:
- return
- await self._write_json(path, {"users": account.users})
+ lease = await self._async_agfs.pathlock_acquire_exact(path, timeout_secs=10.0)
except LockAcquisitionError as exc:
raise ResourceBusyError(
"Another user operation is in progress for this account. Please retry.",
uri=path,
conflict_type="user_registry_busy",
) from exc
+ try:
+ account = self._accounts.get(account_id)
+ if account is None:
+ return
+ await self._write_json(path, {"users": account.users}, lease_ref=lease)
+ finally:
+ await self._async_agfs.pathlock_release(lease)
diff --git a/openviking/server/temp_upload_store.py b/openviking/server/temp_upload_store.py
index e79a6e10f..290394cc7 100644
--- a/openviking/server/temp_upload_store.py
+++ b/openviking/server/temp_upload_store.py
@@ -17,7 +17,7 @@ from typing import Any, Optional
from openviking.server.config import ServerConfig, TempUploadConfig
from openviking.server.identity import RequestContext, Role
from openviking.server.local_input_guard import _read_upload_meta
-from openviking.storage.transaction import get_lock_manager
+from openviking.storage.errors import LockAcquisitionError
from openviking.storage.viking_fs import get_viking_fs
from openviking_cli.exceptions import InvalidArgumentError, PermissionDeniedError
from openviking_cli.utils.config.open_viking_config import get_openviking_config
@@ -36,7 +36,7 @@ class ResolvedTempUpload:
async def cleanup(self) -> None:
if self.lock_handle is not None:
with suppress(Exception):
- await get_lock_manager().release(self.lock_handle)
+ await get_viking_fs()._async_agfs.pathlock_release(self.lock_handle)
self.lock_handle = None
if self.mode == "shared" and self.local_path:
@@ -142,7 +142,12 @@ class TempUploadStore:
meta = await self._read_shared_meta(shared_id, ctx)
meta["state"] = "uploaded"
meta["updated_at"] = int(time.time())
- await self._write_shared_meta(shared_id, ctx, meta)
+ await self._write_shared_meta(
+ shared_id,
+ ctx,
+ meta,
+ lease_ref=resolved.lock_handle,
+ )
async def mark_consumed(self, resolved: ResolvedTempUpload, ctx: RequestContext) -> None:
shared_id = _parse_shared_temp_file_id(resolved.temp_file_id)
@@ -153,7 +158,7 @@ class TempUploadStore:
uri,
recursive=True,
ctx=self._internal_ctx(ctx),
- lock_handle=resolved.lock_handle,
+ lease_ref=resolved.lock_handle,
)
async def try_cleanup_invalid_or_expired(
@@ -315,9 +320,9 @@ class TempUploadStore:
_shared_upload_uri(self.temp_cfg, ctx, upload_id),
ctx=internal_ctx,
)
- handle = get_lock_manager().create_handle()
- acquired = await get_lock_manager().acquire_tree(handle, lock_path, timeout=0.0)
- if not acquired:
+ try:
+ lease = await vfs._async_agfs.pathlock_acquire_tree(lock_path, timeout_secs=0.0)
+ except LockAcquisitionError:
raise PermissionDeniedError("Temporary upload is being consumed.")
try:
@@ -328,7 +333,7 @@ class TempUploadStore:
meta["state"] = "consuming"
meta["updated_at"] = now
- await self._write_shared_meta(upload_id, ctx, meta)
+ await self._write_shared_meta(upload_id, ctx, meta, lease_ref=lease)
file_ext = meta.get("file_ext") or ".tmp"
fd, temp_path = tempfile.mkstemp(prefix="ov_shared_upload_", suffix=file_ext)
@@ -347,11 +352,11 @@ class TempUploadStore:
temp_file_id=temp_file_id,
original_filename=meta.get("original_filename") or None,
local_path=temp_path,
- lock_handle=handle,
+ lock_handle=lease,
)
except Exception:
with suppress(Exception):
- await get_lock_manager().release(handle)
+ await vfs._async_agfs.pathlock_release(lease)
raise
async def _read_shared_meta(self, upload_id: str, ctx: RequestContext) -> dict[str, Any]:
@@ -370,12 +375,15 @@ class TempUploadStore:
upload_id: str,
ctx: RequestContext,
meta: dict[str, Any],
+ lease_ref: Any = None,
) -> None:
+ """Write shared-upload metadata under an optional existing pathlock lease."""
meta_uri = _shared_meta_uri(self.temp_cfg, ctx, upload_id)
await get_viking_fs().write_file(
meta_uri,
json.dumps(meta, ensure_ascii=False),
ctx=self._internal_ctx(ctx),
+ lease_ref=lease_ref,
)
def _validate_shared_meta(
diff --git a/openviking/server/user_config.py b/openviking/server/user_config.py
index 4a93fc776..908d5a858 100644
--- a/openviking/server/user_config.py
+++ b/openviking/server/user_config.py
@@ -12,13 +12,11 @@ from typing import TYPE_CHECKING, Any, AsyncIterator, Callable, Optional, TypeVa
from openviking.core.namespace import canonical_user_root
from openviking.core.uri_validation import validate_content_target_uri
from openviking.server.config import AddTargetsConfig, UserConfig
-from openviking.storage.transaction import LockContext, get_lock_manager
from openviking_cli.exceptions import InvalidArgumentError, NotFoundError
if TYPE_CHECKING:
from openviking.server.config import ServerConfig
from openviking.server.identity import RequestContext
- from openviking.storage.transaction import LockHandle
from openviking.storage.viking_fs import VikingFS
@@ -40,14 +38,20 @@ async def _user_config_lock(
viking_fs: VikingFS,
uri: str,
ctx: RequestContext,
-) -> AsyncIterator[Optional[LockHandle]]:
+) -> AsyncIterator[Optional[dict[str, Any]]]:
uri_to_path = getattr(viking_fs, "_uri_to_path", None)
- if not callable(uri_to_path):
+ agfs = getattr(viking_fs, "_async_agfs", None)
+ acquire = getattr(agfs, "pathlock_acquire_exact", None)
+ release = getattr(agfs, "pathlock_release", None)
+ if not callable(uri_to_path) or not callable(acquire) or not callable(release):
yield None
return
path = uri_to_path(uri, ctx=ctx)
- async with LockContext(get_lock_manager(), [path], lock_mode="exact") as handle:
- yield handle
+ lease = await acquire(path)
+ try:
+ yield lease
+ finally:
+ await release(lease)
def _user_config_from_payload(payload: Any) -> UserConfig:
@@ -156,7 +160,7 @@ async def update_user_config(
sort_keys=True,
),
ctx=ctx,
- lock_handle=handle,
+ lease_ref=handle,
)
return result
@@ -177,7 +181,7 @@ async def write_user_config(
sort_keys=True,
),
ctx=ctx,
- lock_handle=handle,
+ lease_ref=handle,
)
return runtime
diff --git a/openviking/service/core.py b/openviking/service/core.py
index 98a13f81d..ca3964804 100644
--- a/openviking/service/core.py
+++ b/openviking/service/core.py
@@ -31,7 +31,6 @@ from openviking.storage.index_consistency import check_index_consistency
from openviking.storage.queuefs.add_resource_processor import AddResourceProcessor
from openviking.storage.queuefs.queue_manager import QueueManager, init_queue_manager
from openviking.storage.queuefs.session_commit_processor import SessionCommitProcessor
-from openviking.storage.transaction import LockManager, init_lock_manager
from openviking.storage.viking_fs import VikingFS, init_viking_fs
from openviking.utils.agfs_utils import (
build_runtime_ragfs_binding_config,
@@ -88,7 +87,7 @@ class OpenVikingService:
self._resource_processor: Optional[ResourceProcessor] = None
self._skill_processor: Optional[SkillProcessor] = None
self._session_compressor: Optional["SessionCompressorV2"] = None
- self._lock_manager: Optional[LockManager] = None
+
self._directory_initializer: Optional[DirectoryInitializer] = None
self._watch_scheduler: Optional[WatchScheduler] = None
self._encryptor: Optional[Any] = None
@@ -173,16 +172,7 @@ class OpenVikingService:
if self._queue_manager:
self._queue_manager.setup_standard_queues(self._vikingdb_manager, start=False)
- # Initialize LockManager (fail-fast if RAGFS missing)
- if self._agfs_client is None:
- raise RuntimeError("RAGFS client not initialized for LockManager")
- tx_cfg = config.transaction
- self._lock_manager = init_lock_manager(
- agfs=self._agfs_client,
- lock_timeout=tx_cfg.lock_timeout,
- lock_expire=tx_cfg.lock_expire,
- redo_recovery_enabled=tx_cfg.redo_recovery_enabled,
- )
+ # PathLock has been moved to Rust ragfs; Python-layer LockManager is no longer needed.
set_task_tracker(config.build_task_tracker(self._agfs_client))
def _build_ragfs_binding_config(self) -> Any:
@@ -232,11 +222,6 @@ class OpenVikingService:
"""Get VikingDBManager instance."""
return self._vikingdb_manager
- @property
- def lock_manager(self) -> Optional[LockManager]:
- """Get LockManager instance."""
- return self._lock_manager
-
@property
def session_compressor(self) -> Optional["SessionCompressorV2"]:
"""Get SessionCompressor instance."""
@@ -376,11 +361,6 @@ class OpenVikingService:
skill_processor=self._skill_processor,
)
- # Start LockManager if initialized
- if self._lock_manager:
- await self._lock_manager.start()
- logger.info("LockManager started")
-
self._watch_scheduler = WatchScheduler(
resource_service=self._resource_service,
viking_fs=self._viking_fs,
@@ -437,6 +417,7 @@ class OpenVikingService:
self._resource_service,
asyncio.get_running_loop(),
queue_name,
+ self._viking_fs,
),
allow_create=True,
)
@@ -476,10 +457,6 @@ class OpenVikingService:
self._queue_manager = None
logger.info("Queue manager stopped")
- if self._lock_manager:
- await self._lock_manager.stop()
- self._lock_manager = None
-
if self._vikingdb_manager:
self._vikingdb_manager.mark_closing()
diff --git a/openviking/service/debug_service.py b/openviking/service/debug_service.py
index d0a8f8625..eccde2ee2 100644
--- a/openviking/service/debug_service.py
+++ b/openviking/service/debug_service.py
@@ -11,14 +11,14 @@ from openviking.server.identity import RequestContext
from openviking.storage import VikingDBManager
from openviking.storage.observers import (
FilesystemObserver,
- LockObserver,
ModelsObserver,
QueueObserver,
RetrievalObserver,
VikingDBObserver,
)
from openviking.storage.queuefs import get_queue_manager
-from openviking.storage.transaction import get_lock_manager
+from openviking.storage.viking_fs import get_viking_fs
+from openviking_cli.utils import run_async
from openviking_cli.utils.config import OpenVikingConfig
from openviking_cli.utils.logger import get_logger
@@ -165,9 +165,10 @@ class ObserverService:
@property
def lock(self) -> ComponentStatus:
- """Get lock system status."""
+ """Get lock system status via pathlock_observe snapshot."""
try:
- lock_manager = get_lock_manager()
+ viking_fs = get_viking_fs()
+ snapshot = run_async(viking_fs._async_agfs.pathlock_observe())
except Exception:
return ComponentStatus(
name="lock",
@@ -175,12 +176,22 @@ class ObserverService:
has_errors=True,
status="Not initialized",
)
- observer = LockObserver(lock_manager)
+ active = snapshot.get("active_locks", 0)
+ waiting = snapshot.get("waiting_locks", 0)
+ stale = snapshot.get("stale_locks_removed", 0)
+ conflicts = snapshot.get("conflicts", [])
+ has_errors = bool(conflicts) or stale > 0
+ lines = [
+ f"Active locks: {active}",
+ f"Waiting locks: {waiting}",
+ f"Stale locks removed: {stale}",
+ f"Conflicts: {len(conflicts)}",
+ ]
return ComponentStatus(
name="lock",
- is_healthy=observer.is_healthy(),
- has_errors=observer.has_errors(),
- status=observer.get_status_table(),
+ is_healthy=not has_errors,
+ has_errors=has_errors,
+ status="\n".join(lines),
)
@property
@@ -222,10 +233,8 @@ class ObserverService:
# Call get_stats on the RAGFS client
import asyncio
- stats = await asyncio.to_thread(
- self._agfs_client.get_stats,
- mount_path
- )
+
+ stats = await asyncio.to_thread(self._agfs_client.get_stats, mount_path)
return stats
except Exception as e:
logger.error(f"Error getting filesystem stats: {e}")
diff --git a/openviking/service/reindex_executor.py b/openviking/service/reindex_executor.py
index 57a261024..9789a178f 100644
--- a/openviking/service/reindex_executor.py
+++ b/openviking/service/reindex_executor.py
@@ -31,13 +31,6 @@ from openviking.storage.expr import And, Eq, Or, PathScope
from openviking.storage.queuefs.embedding_msg_converter import EmbeddingMsgConverter
from openviking.storage.queuefs.semantic_msg import SemanticMsg
from openviking.storage.queuefs.semantic_processor import SemanticProcessor
-from openviking.storage.transaction import (
- NO_LOCK,
- BorrowedLockLease,
- LockContext,
- LockLease,
- get_lock_manager,
-)
from openviking.storage.viking_fs import get_viking_fs
from openviking.telemetry import get_current_telemetry
from openviking.telemetry.request_wait_tracker import get_request_wait_tracker
@@ -104,7 +97,7 @@ class _ReindexCounters:
class _ReindexRunContext:
ctx: RequestContext
counters: _ReindexCounters
- lock: LockLease = NO_LOCK
+ lock: dict | None = None
@dataclass
@@ -442,71 +435,73 @@ class ReindexExecutor:
if telemetry_id:
wait_tracker.register_request(telemetry_id)
+ lease = await service.viking_fs._async_agfs.pathlock_acquire_tree(path)
try:
- async with LockContext(get_lock_manager(), [path], lock_mode="tree") as lock_handle:
- run = _ReindexRunContext(
- ctx=ctx,
+ borrowed = await service.viking_fs._async_agfs.pathlock_as_borrowed(lease)
+ run = _ReindexRunContext(
+ ctx=ctx,
+ counters=counters,
+ lock=borrowed,
+ )
+ if mode == "prune_orphans":
+ await self._prune_orphan_vectors(
+ uri=uri,
+ object_type=object_type,
+ dry_run=dry_run,
counters=counters,
- lock=BorrowedLockLease.from_handle(get_lock_manager(), lock_handle),
+ ctx=ctx,
+ )
+ elif object_type == "global_namespace":
+ await self._reindex_global_namespace(
+ uri=uri,
+ mode=mode,
+ run=run,
+ )
+ elif object_type == "user_namespace":
+ await self._reindex_user_namespace(
+ uri=uri,
+ mode=mode,
+ run=run,
+ )
+ elif object_type == "skill_namespace":
+ await self._reindex_skill_namespace(
+ uri=uri,
+ mode=mode,
+ run=run,
+ )
+ elif object_type == "resource":
+ await self._reindex_resource(
+ uri=uri,
+ mode=mode,
+ run=run,
+ )
+ elif object_type == "skill":
+ await self._reindex_skill(
+ uri=uri,
+ mode=mode,
+ run=run,
+ )
+ elif object_type == "memory":
+ await self._reindex_memory(
+ uri=uri,
+ mode=mode,
+ run=run,
+ )
+ else:
+ raise OpenVikingError(
+ f"Unsupported reindex type: {object_type}",
+ code="UNSUPPORTED_URI",
+ details={"uri": uri},
)
- if mode == "prune_orphans":
- await self._prune_orphan_vectors(
- uri=uri,
- object_type=object_type,
- dry_run=dry_run,
- counters=counters,
- ctx=ctx,
- )
- elif object_type == "global_namespace":
- await self._reindex_global_namespace(
- uri=uri,
- mode=mode,
- run=run,
- )
- elif object_type == "user_namespace":
- await self._reindex_user_namespace(
- uri=uri,
- mode=mode,
- run=run,
- )
- elif object_type == "skill_namespace":
- await self._reindex_skill_namespace(
- uri=uri,
- mode=mode,
- run=run,
- )
- elif object_type == "resource":
- await self._reindex_resource(
- uri=uri,
- mode=mode,
- run=run,
- )
- elif object_type == "skill":
- await self._reindex_skill(
- uri=uri,
- mode=mode,
- run=run,
- )
- elif object_type == "memory":
- await self._reindex_memory(
- uri=uri,
- mode=mode,
- run=run,
- )
- else:
- raise OpenVikingError(
- f"Unsupported reindex type: {object_type}",
- code="UNSUPPORTED_URI",
- details={"uri": uri},
- )
- if telemetry_id and mode != "prune_orphans":
- await wait_tracker.wait_for_request(telemetry_id)
- self._apply_embedding_wait_status(
- counters,
- wait_tracker.build_queue_status(telemetry_id),
- )
+ if telemetry_id and mode != "prune_orphans":
+ await wait_tracker.wait_for_request(telemetry_id)
+ self._apply_embedding_wait_status(
+ counters,
+ wait_tracker.build_queue_status(telemetry_id),
+ )
finally:
+ await service.viking_fs._async_agfs.pathlock_release(lease)
if telemetry_id:
wait_tracker.cleanup(telemetry_id)
@@ -916,7 +911,7 @@ class ReindexExecutor:
uri: str,
context_type: str,
ctx: RequestContext,
- lock: LockLease = NO_LOCK,
+ lock: dict | None = None,
) -> None:
processor = SemanticProcessor(
max_concurrent_llm=get_openviking_config().vlm.max_concurrent,
@@ -932,7 +927,7 @@ class ReindexExecutor:
role=str(ctx.role),
skip_vectorization=True,
)
- await processor.on_dequeue({"data": msg.to_json()}, lock=lock.as_borrowed())
+ await processor.on_dequeue({"data": msg.to_json()}, lock=lock)
async def _reindex_resource_vectors(
self,
@@ -1092,7 +1087,8 @@ class ReindexExecutor:
viking_fs = get_viking_fs()
marker_name = ".abstract.md" if level == ContextLevel.ABSTRACT else ".overview.md"
lock_path = viking_fs._uri_to_path(f"{dir_uri}/{marker_name}", ctx=ctx)
- async with LockContext(get_lock_manager(), [lock_path], lock_mode="exact"):
+ lease = await viking_fs._async_agfs.pathlock_acquire_exact(lock_path)
+ try:
abstract = await self._read_directory_abstract(dir_uri, ctx=ctx)
if level == ContextLevel.ABSTRACT:
vector_text = abstract
@@ -1114,6 +1110,8 @@ class ReindexExecutor:
level=level,
ctx=ctx,
)
+ finally:
+ await viking_fs._async_agfs.pathlock_release(lease)
async def delete_uri_level(self, *, uri: str, level: ContextLevel, ctx: RequestContext) -> int:
"""Delete ONLY the vector record at ``(uri, level)``. Returns count.
diff --git a/openviking/service/resource_service.py b/openviking/service/resource_service.py
index 3036d0a91..7be5ef7d7 100644
--- a/openviking/service/resource_service.py
+++ b/openviking/service/resource_service.py
@@ -42,7 +42,6 @@ from openviking.server.user_config import (
)
from openviking.storage import VikingDBManager
from openviking.storage.queuefs import QueueManager, get_queue_manager
-from openviking.storage.transaction import NO_LOCK, LockLease
from openviking.storage.viking_fs import VikingFS
from openviking.telemetry import get_current_telemetry
from openviking.telemetry.request_wait_tracker import get_request_wait_tracker
@@ -382,6 +381,47 @@ class ResourceService:
if not self._viking_fs:
raise NotInitializedError("VikingFS")
+ async def _lock_to_handoff_payload(self, lock_ref: Any) -> Optional[Dict[str, Any]]:
+ """Convert either a native pathlock ref or legacy lease into a handoff payload."""
+ if lock_ref is None:
+ return None
+ async_agfs = getattr(self._viking_fs, "_async_agfs", None)
+ if async_agfs is not None:
+ return await async_agfs.pathlock_to_handoff(lock_ref)
+ to_handoff = getattr(lock_ref, "to_handoff", None)
+ if callable(to_handoff):
+ handoff = to_handoff()
+ return handoff.to_dict() if hasattr(handoff, "to_dict") else handoff
+ return lock_ref if isinstance(lock_ref, dict) else None
+
+ async def _handoff_lock_ref(self, lock_ref: Any) -> None:
+ """Transfer ownership for either a native pathlock ref or legacy lease."""
+ if lock_ref is None:
+ return
+ async_agfs = getattr(self._viking_fs, "_async_agfs", None)
+ if async_agfs is not None:
+ await async_agfs.pathlock_handoff(lock_ref)
+ return
+ handoff = getattr(lock_ref, "handoff", None)
+ if callable(handoff):
+ result = handoff()
+ if inspect.isawaitable(result):
+ await result
+
+ async def _release_lock_ref(self, lock_ref: Any) -> None:
+ """Release either a native pathlock ref or legacy lease."""
+ if lock_ref is None:
+ return
+ async_agfs = getattr(self._viking_fs, "_async_agfs", None)
+ if async_agfs is not None:
+ await async_agfs.pathlock_release(lock_ref)
+ return
+ close = getattr(lock_ref, "close", None)
+ if callable(close):
+ result = close()
+ if inspect.isawaitable(result):
+ await result
+
async def close_background_tasks(self) -> None:
"""Cancel in-flight connector monitoring tasks during service shutdown."""
if not self._background_tasks:
@@ -397,33 +437,36 @@ class ResourceService:
msg: Any,
*,
queue_name: str,
- resource_lock: LockLease = NO_LOCK,
+ resource_lock: Optional[Dict[str, Any]] = None,
) -> Any:
- """Persist a job before its TaskRecord so a crash cannot orphan the task."""
+ """Persist a job and fully own the passed lock until handoff or release completes."""
from openviking.service.task_tracker import get_task_tracker
from openviking.storage.queuefs import get_queue_manager
+ tracker = get_task_tracker()
try:
await get_queue_manager().enqueue(queue_name, msg.to_dict())
- await resource_lock.handoff()
+ if resource_lock is not None:
+ await self._handoff_lock_ref(resource_lock)
+ resource_lock = None
+ task = await tracker.create(
+ "add_resource",
+ resource_id=None if msg.defer_target_resolution else msg.root_uri,
+ account_id=msg.account_id,
+ user_id=msg.user_id,
+ task_id=msg.task_id,
+ )
+ await tracker.update_stage(
+ task.task_id,
+ "queued",
+ account_id=msg.account_id,
+ user_id=msg.user_id,
+ )
except BaseException:
- await resource_lock.close()
+ if resource_lock is not None:
+ await self._release_lock_ref(resource_lock)
raise
- tracker = get_task_tracker()
- task = await tracker.create(
- "add_resource",
- resource_id=None if msg.defer_target_resolution else msg.root_uri,
- account_id=msg.account_id,
- user_id=msg.user_id,
- task_id=msg.task_id,
- )
- await tracker.update_stage(
- task.task_id,
- "queued",
- account_id=msg.account_id,
- user_id=msg.user_id,
- )
return task
async def execute_add_resource_job(
@@ -431,11 +474,10 @@ class ResourceService:
msg: Any,
*,
ctx: RequestContext,
- resource_lock: Optional[LockLease],
+ resource_lock: Optional[Dict[str, Any]],
stage_callback: Callable[[str], Any],
) -> Dict[str, Any]:
"""Execute one durable add-resource job inside its QueueFS consumer."""
- resource_lock = resource_lock or NO_LOCK
if msg.prepared is None:
target_uri = msg.root_uri
parent_uri = None
@@ -534,18 +576,15 @@ class ResourceService:
self,
root_uri: str,
ctx: RequestContext,
- ) -> LockLease:
+ ) -> Dict[str, Any]:
"""Acquire a fresh lock when a recovered job's old handoff was released."""
if not self._resource_processor or not self._viking_fs:
raise NotInitializedError("ResourceProcessor")
- from openviking.storage.transaction import get_lock_manager
dst_path = self._viking_fs._uri_to_path(root_uri, ctx=ctx)
- return await self._resource_processor.acquire_resource_lock(
- get_lock_manager(),
+ return await self._viking_fs._async_agfs.pathlock_acquire_tree(
dst_path,
- uri=root_uri,
- timeout=0.0,
+ timeout_secs=0.0,
)
async def enqueue_git_add_resource(
@@ -596,7 +635,7 @@ class ResourceService:
from openviking.storage.queuefs.add_resource_msg import AddResourceMsg
- resource_lock: LockLease = NO_LOCK
+ resource_lock: Optional[Dict[str, Any]] = None
try:
if enforce_public_remote_targets and is_remote_resource_source(path):
path = require_remote_resource_source(path)
@@ -615,7 +654,11 @@ class ResourceService:
)
task_id = str(uuid4())
- lock_handoff = resource_lock.to_handoff()
+ lock_handoff = (
+ await self._viking_fs._async_agfs.pathlock_to_handoff(resource_lock)
+ if resource_lock is not None
+ else None
+ )
processor_args = {
key: value
for key, value in kwargs.items()
@@ -630,7 +673,7 @@ class ResourceService:
user_id=ctx.user.user_id,
role=str(ctx.role),
actor_peer_id=ctx.actor_peer_id,
- lock_handoff=lock_handoff.to_dict() if lock_handoff else None,
+ lock_handoff=lock_handoff,
reason=reason,
instruction=instruction,
timeout=timeout,
@@ -653,19 +696,21 @@ class ResourceService:
source_name=source_name,
args=self._processor_args_for_watch_run(processor_args),
)
+ enqueue_lock = resource_lock
+ resource_lock = None
task = await self._enqueue_add_resource_job(
msg,
queue_name=QueueManager.ADD_RESOURCE,
- resource_lock=resource_lock,
+ resource_lock=enqueue_lock,
)
- resource_lock = NO_LOCK
return {
"status": "success",
"root_uri": root_uri,
"task_id": task.task_id,
}
except Exception:
- await resource_lock.close()
+ if resource_lock is not None:
+ await self._viking_fs._async_agfs.pathlock_release(resource_lock)
raise
async def _plan_resource_target(
@@ -676,7 +721,7 @@ class ResourceService:
target: ContentTargetSpec,
source_name: Optional[str],
source_info: _ResourceSourceInfo,
- ) -> tuple[str, LockLease]:
+ ) -> tuple[str, Optional[Dict[str, Any]]]:
if not self._resource_processor or not self._viking_fs:
raise NotInitializedError("ResourceProcessor")
@@ -698,14 +743,10 @@ class ResourceService:
ctx=ctx,
)
- from openviking.storage.transaction import get_lock_manager
-
dst_path = self._viking_fs._uri_to_path(root_uri, ctx=ctx)
- resource_lock = await self._resource_processor.acquire_resource_lock(
- get_lock_manager(),
+ resource_lock = await self._viking_fs._async_agfs.pathlock_acquire_tree(
dst_path,
- uri=root_uri,
- timeout=0.0,
+ timeout_secs=0.0,
)
return root_uri, resource_lock
@@ -1037,7 +1078,7 @@ class ResourceService:
enforce_public_remote_targets: bool = False,
watch_auth_state: Optional[Dict[str, Any]] = None,
parser_args: Optional[Dict[str, Any]] = None,
- resource_lock: Optional[LockLease] = None,
+ resource_lock: Optional[Dict[str, Any]] = None,
stage_callback: Optional[Callable[[str], Any]] = None,
**kwargs,
) -> Dict[str, Any]:
@@ -1048,7 +1089,7 @@ class ResourceService:
telemetry_id = register_wait_telemetry(wait)
request_wait_tracker = get_request_wait_tracker()
job_enqueued = False
- deferred_lock: LockLease = NO_LOCK
+ deferred_lock: Optional[Dict[str, Any]] = None
ingest_tag_kwargs = self._add_resource_ingest_tag_kwargs(
tags=tags,
tag_mode=tag_mode,
@@ -1158,19 +1199,18 @@ class ResourceService:
)
if self._viking_fs is None:
raise NotInitializedError("VikingFS")
- from openviking.storage.errors import LockAcquisitionError, ResourceBusyError
- from openviking.storage.transaction import OwnedLockLease, get_lock_manager
+ from openviking.storage.errors import ResourceBusyError
- lock_manager = get_lock_manager()
- lock_lease: LockLease = NO_LOCK
+ lock_lease: Optional[Dict[str, Any]] = None
- async def _reserve_tree(uri: str) -> LockLease:
+ async def _reserve_tree(uri: str) -> Dict[str, Any]:
dst_path = self._viking_fs._uri_to_path(uri, ctx=ctx)
try:
- return await OwnedLockLease.acquire_tree(
- lock_manager, dst_path, timeout=0.0
+ return await self._viking_fs._async_agfs.pathlock_acquire_tree(
+ dst_path,
+ timeout_secs=0.0,
)
- except LockAcquisitionError as exc:
+ except Exception as exc:
raise ResourceBusyError(
f"Resource is busy: {uri}",
uri=uri,
@@ -1203,7 +1243,7 @@ class ResourceService:
if resolved_extension:
processor_args["resolved_extension"] = resolved_extension
- lock_handoff = lock_lease.to_handoff()
+ lock_handoff = await self._lock_to_handoff_payload(lock_lease)
msg = AddResourceMsg(
task_id=str(uuid4()),
telemetry_id=telemetry_id or None,
@@ -1230,7 +1270,7 @@ class ResourceService:
enforce_public_remote_targets=enforce_public_remote_targets,
args=processor_args,
source_name=source_name,
- lock_handoff=lock_handoff.to_dict() if lock_handoff else None,
+ lock_handoff=lock_handoff,
skip_watch_management=True,
defer_target_resolution=defer_target_resolution,
understanding_response_id=understanding_response_id,
@@ -1238,16 +1278,17 @@ class ResourceService:
tag_mode=tag_mode,
)
enqueue_started = True
+ enqueue_lock = lock_lease
+ lock_lease = None
task = await self._enqueue_add_resource_job(
msg,
queue_name=QueueManager.EXTERNAL_PARSE,
- resource_lock=lock_lease,
+ resource_lock=enqueue_lock,
)
except BaseException:
- if not enqueue_started:
- await lock_lease.close()
+ if not enqueue_started and lock_lease is not None:
+ await self._release_lock_ref(lock_lease)
raise
- lock_lease = NO_LOCK
job_enqueued = True
logger.info(
"[ResourceService] Enqueued AddResourceMsg task_id=%s root_uri=%s",
@@ -1301,7 +1342,7 @@ class ResourceService:
if result.get("status") == "error":
return result
prepared = result.pop("_post_process", None)
- deferred_lock = result.pop("_resource_lock", NO_LOCK)
+ deferred_lock = result.pop("_resource_lock", None)
if wait:
if stage_callback is not None:
stage_result = stage_callback("processing_queue")
@@ -1355,7 +1396,7 @@ class ResourceService:
root_uri = result.get("root_uri", "")
if not isinstance(prepared, dict):
raise InternalError("Deferred resource processing payload is missing")
- lock_handoff = deferred_lock.to_handoff()
+ lock_handoff = await self._lock_to_handoff_payload(deferred_lock)
msg = AddResourceMsg(
task_id=str(uuid4()),
root_uri=root_uri,
@@ -1365,7 +1406,7 @@ class ResourceService:
user_id=ctx.user.user_id,
role=str(ctx.role),
actor_peer_id=ctx.actor_peer_id,
- lock_handoff=lock_handoff.to_dict() if lock_handoff else None,
+ lock_handoff=lock_handoff,
reason=reason,
instruction=instruction,
timeout=timeout,
@@ -1386,12 +1427,13 @@ class ResourceService:
tags=tags,
tag_mode=tag_mode,
)
+ enqueue_lock = deferred_lock
+ deferred_lock = None
task = await self._enqueue_add_resource_job(
msg,
queue_name=QueueManager.ADD_RESOURCE,
- resource_lock=deferred_lock,
+ resource_lock=enqueue_lock,
)
- deferred_lock = NO_LOCK
result["task_id"] = task.task_id
job_enqueued = True
await self._manage_watch_if_needed(
@@ -1436,8 +1478,8 @@ class ResourceService:
if wait or not telemetry_id or not job_enqueued:
get_request_wait_tracker().cleanup(telemetry_id)
unregister_wait_telemetry(telemetry_id)
- if deferred_lock.active:
- await deferred_lock.close()
+ if deferred_lock is not None:
+ await self._release_lock_ref(deferred_lock)
async def _link_resource_reason_memory(
self,
diff --git a/openviking/session/compressor_v2.py b/openviking/session/compressor_v2.py
index 8322cd048..8b19a3705 100644
--- a/openviking/session/compressor_v2.py
+++ b/openviking/session/compressor_v2.py
@@ -179,7 +179,9 @@ class SessionCompressorV2:
Always create new instance to avoid cross-request state pollution.
"""
return MemoryUpdater(
- registry=registry, vikingdb=self.vikingdb, transaction_handle=transaction_handle
+ registry=registry,
+ vikingdb=self.vikingdb,
+ transaction_handle=transaction_handle,
)
def _split_operations_by_memory_type(
@@ -282,17 +284,14 @@ class SessionCompressorV2:
telemetry.set("memory.extract.deleted", 0)
telemetry.set("memory.extract.skipped", 0)
- from openviking.storage.transaction import get_lock_manager, init_lock_manager
+ from openviking.storage.errors import LockAcquisitionError
- # 初始化锁管理器(仅在有 AGFS 时使用锁机制)
+ # 初始化锁(仅在有 AGFS 时使用锁机制)
viking_fs = get_viking_fs()
- lock_manager = None
+ lease = None
transaction_handle = None
- if viking_fs and hasattr(viking_fs, "agfs") and viking_fs.agfs:
- init_lock_manager(viking_fs.agfs)
- lock_manager = get_lock_manager()
- transaction_handle = lock_manager.create_handle()
- else:
+ has_agfs = viking_fs and hasattr(viking_fs, "agfs") and viking_fs.agfs
+ if not has_agfs:
logger.debug("AGFS unavailable, running memory extraction without locks")
try:
@@ -330,7 +329,7 @@ class SessionCompressorV2:
context_provider=context_provider,
)
read_scope = isolation_handler.get_read_scope()
- if lock_manager:
+ if has_agfs:
schemas = orchestrator.context_provider.get_memory_schemas(ctx)
exact_lock_paths, tree_lock_dirs = _render_memory_schema_locks(
schemas=schemas,
@@ -350,28 +349,30 @@ class SessionCompressorV2:
# 循环重试获取锁(机制确保不会死锁)
while True:
- lock_acquired = await lock_manager.acquire_exact_tree_batch(
- transaction_handle,
- exact_paths=exact_lock_paths,
- tree_paths=tree_lock_dirs,
- timeout=None,
- )
- if lock_acquired:
+ try:
+ lease = await viking_fs._async_agfs.pathlock_acquire_exact_tree_batch(
+ exact_lock_paths,
+ tree_lock_dirs,
+ timeout_secs=0.1,
+ )
break
- retry_count += 1
- if max_retries > 0 and retry_count >= max_retries:
- raise TimeoutError(
- "Failed to acquire memory locks after "
- f"{retry_count} retries (max={max_retries})"
+ except LockAcquisitionError:
+ retry_count += 1
+ if max_retries > 0 and retry_count >= max_retries:
+ raise TimeoutError(
+ "Failed to acquire memory locks after "
+ f"{retry_count} retries (max={max_retries})"
+ )
+
+ last_lock_retry_warning_at = _log_memory_lock_retry(
+ retry_count=retry_count,
+ max_retries=max_retries,
+ last_warning_at=last_lock_retry_warning_at,
)
+ if retry_interval > 0:
+ await asyncio.sleep(retry_interval)
- last_lock_retry_warning_at = _log_memory_lock_retry(
- retry_count=retry_count,
- max_retries=max_retries,
- last_warning_at=last_lock_retry_warning_at,
- )
- if retry_interval > 0:
- await asyncio.sleep(retry_interval)
+ transaction_handle = lease
orchestrator._transaction_handle = transaction_handle # 传递给 ExtractLoop
@@ -469,12 +470,12 @@ class SessionCompressorV2:
raise
return []
finally:
- # 确保释放所有锁(仅在有锁管理器时)
- if lock_manager and transaction_handle:
+ # 确保释放所有锁
+ if lease is not None:
try:
- await lock_manager.release(transaction_handle)
+ await viking_fs._async_agfs.pathlock_release(lease)
except Exception as e:
- logger.warning(f"Failed to release transaction lock: {e}")
+ logger.warning(f"Failed to release pathlock: {e}")
@staticmethod
def _empty_memory_diff(archive_uri: str = "") -> Dict[str, Any]:
@@ -592,7 +593,7 @@ class SessionCompressorV2:
async def _append_sources_before_unlock(
result: MemoryUpdateResult,
inheritance_map: Dict[str, List[str]],
- lock_handle: Any,
+ lease_ref: Any,
exp_provider=exp_provider,
exp_dir=exp_dir,
traj_uri=traj_uri,
@@ -612,7 +613,7 @@ class SessionCompressorV2:
source_uris,
ctx,
viking_fs,
- lock_handle=lock_handle,
+ lease_ref=lease_ref,
)
exp_result = await self._run_extract_phase(
@@ -732,7 +733,7 @@ class SessionCompressorV2:
Returns None on failure (unless strict_extract_errors is True, in which case
the exception is re-raised).
"""
- from openviking.storage.transaction import get_lock_manager, init_lock_manager
+ from openviking.storage.errors import LockAcquisitionError
config = get_openviking_config()
vlm = config.vlm.get_vlm_instance()
@@ -764,15 +765,12 @@ class SessionCompressorV2:
thinking=thinking,
)
- lock_manager = None
+ lease = None
transaction_handle = None
- if viking_fs and hasattr(viking_fs, "agfs") and viking_fs.agfs:
- init_lock_manager(viking_fs.agfs)
- lock_manager = get_lock_manager()
- transaction_handle = lock_manager.create_handle()
+ has_agfs = viking_fs and hasattr(viking_fs, "agfs") and viking_fs.agfs
try:
- if lock_manager:
+ if has_agfs:
schemas = [
schema
for schema in provider.get_memory_schemas(ctx)
@@ -792,28 +790,30 @@ class SessionCompressorV2:
retry_count = 0
last_lock_retry_warning_at = 0.0
while True:
- lock_acquired = await lock_manager.acquire_exact_tree_batch(
- transaction_handle,
- exact_paths=exact_lock_paths,
- tree_paths=tree_lock_dirs,
- timeout=None,
- )
- if lock_acquired:
+ try:
+ lease = await viking_fs._async_agfs.pathlock_acquire_exact_tree_batch(
+ exact_lock_paths,
+ tree_lock_dirs,
+ timeout_secs=0.1,
+ )
break
- retry_count += 1
- if max_retries > 0 and retry_count >= max_retries:
- raise TimeoutError(
- f"[{phase_label}] Failed to acquire memory locks after "
- f"{retry_count} retries (max={max_retries})"
+ except LockAcquisitionError:
+ retry_count += 1
+ if max_retries > 0 and retry_count >= max_retries:
+ raise TimeoutError(
+ f"[{phase_label}] Failed to acquire memory locks after "
+ f"{retry_count} retries (max={max_retries})"
+ )
+ last_lock_retry_warning_at = _log_memory_lock_retry(
+ retry_count=retry_count,
+ max_retries=max_retries,
+ last_warning_at=last_lock_retry_warning_at,
+ phase_label=phase_label,
)
- last_lock_retry_warning_at = _log_memory_lock_retry(
- retry_count=retry_count,
- max_retries=max_retries,
- last_warning_at=last_lock_retry_warning_at,
- phase_label=phase_label,
- )
- if retry_interval > 0:
- await asyncio.sleep(retry_interval)
+ if retry_interval > 0:
+ await asyncio.sleep(retry_interval)
+
+ transaction_handle = lease
provider._transaction_handle = transaction_handle
orchestrator._transaction_handle = transaction_handle
@@ -916,11 +916,11 @@ class SessionCompressorV2:
raise
return None
finally:
- if lock_manager and transaction_handle:
+ if lease is not None:
try:
- await lock_manager.release(transaction_handle)
+ await viking_fs._async_agfs.pathlock_release(lease)
except Exception as e:
- logger.warning(f"[{phase_label}] Failed to release transaction lock: {e}")
+ logger.warning(f"[{phase_label}] Failed to release pathlock: {e}")
async def _resolve_supersedes(
self,
@@ -997,7 +997,7 @@ class SessionCompressorV2:
traj_uris: List[str],
ctx,
viking_fs,
- lock_handle: Optional[Any] = None,
+ lease_ref: Optional[Any] = None,
) -> None:
"""Write bidirectional StoredLinks between traj_uris and each exp file.
@@ -1010,33 +1010,28 @@ class SessionCompressorV2:
for exp_uri in exp_uris:
try:
- try:
- from openviking.storage.transaction import LockContext, get_lock_manager
+ lease = lease_ref
+ owns_lease = False
+ if lease is None:
+ lock_path = viking_fs._uri_to_path(exp_uri, ctx=ctx)
+ try:
+ lease = await viking_fs._async_agfs.pathlock_acquire_exact(lock_path)
+ owns_lease = True
+ except Exception as e:
+ logger.warning(f"Failed to acquire trajectory metadata lock: {e}")
+ continue
- lock_manager = get_lock_manager()
- except Exception:
- await self._append_trajectory_metadata(
- exp_uri,
- normalized_traj_uris,
- ctx,
- viking_fs,
- )
- continue
-
- lock_path = viking_fs._uri_to_path(exp_uri, ctx=ctx)
- async with LockContext(
- lock_manager,
- [lock_path],
- lock_mode="exact",
- handle=lock_handle,
- ) as active_lock_handle:
+ try:
await self._append_trajectory_metadata(
exp_uri,
normalized_traj_uris,
ctx,
viking_fs,
- lock_handle=active_lock_handle,
+ lease_ref=lease,
)
+ finally:
+ if owns_lease:
+ await viking_fs._async_agfs.pathlock_release(lease)
except Exception as e:
logger.warning(f"Failed to append source trajectories to {exp_uri}: {e}")
@@ -1046,7 +1041,7 @@ class SessionCompressorV2:
traj_uris: List[str],
ctx,
viking_fs,
- lock_handle=None,
+ lease_ref=None,
) -> None:
from datetime import timezone
@@ -1070,12 +1065,11 @@ class SessionCompressorV2:
mf.links = new_exp_links
if links_changed:
- # TODO: This must be optimized once pathlock is pushed down into ragfs.
await viking_fs.write_file(
exp_uri,
MemoryFileUtils.write(mf),
ctx=ctx,
- lock_handle=lock_handle,
+ lease_ref=lease_ref,
)
tracer.info(
f"[agent_link] wrote exp→traj links -> {exp_uri} (traj_count={len(traj_uris)})"
@@ -1084,7 +1078,7 @@ class SessionCompressorV2:
tracer.info(f"[agent_link] links already present, skip: {exp_uri}")
# Write traj.backlinks — exp_uri already handled above
- await write_stored_links(links, ctx, viking_fs, skip_uris={exp_uri})
+ await write_stored_links(links, ctx, viking_fs, skip_uris={exp_uri}, lease_ref=lease_ref)
async def _build_memory_diff(
self,
diff --git a/openviking/session/compressor_v3.py b/openviking/session/compressor_v3.py
index a198817e3..7838d16eb 100644
--- a/openviking/session/compressor_v3.py
+++ b/openviking/session/compressor_v3.py
@@ -184,7 +184,6 @@ class SessionCompressorV3:
return MemoryUpdater(
registry=registry,
vikingdb=self.vikingdb,
- transaction_handle=transaction_handle,
)
async def _build_memory_diff(
diff --git a/openviking/session/memory/memory_updater.py b/openviking/session/memory/memory_updater.py
index 7596fdc80..2cd9da81e 100644
--- a/openviking/session/memory/memory_updater.py
+++ b/openviking/session/memory/memory_updater.py
@@ -76,14 +76,13 @@ async def write_stored_links(
ctx: RequestContext,
viking_fs: Any,
skip_uris: Optional[set] = None,
- lock_handle: Any = None,
+ lease_ref: Any = None,
) -> List[str]:
"""Write StoredLinks to their endpoint files' links/backlinks fields.
For each link: from_uri's ``links`` receives the forward link;
to_uri's ``backlinks`` receives the reverse reference.
Files listed in skip_uris are skipped (caller handles them in the same write).
- When lock_handle is provided, all endpoint rewrites reuse that transaction.
Returns the endpoint URIs that were successfully rewritten. Callers can
use this to avoid reporting link-only edits for files that failed the
read/modify/write step.
@@ -91,7 +90,6 @@ async def write_stored_links(
from openviking.session.memory.merge_op.link_merge import merge_links
skip = skip_uris or set()
- lock_kwargs = {"lock_handle": lock_handle} if lock_handle is not None else {}
file_links: Dict[str, Dict[str, List[StoredLink]]] = {}
for link in links:
if link.from_uri not in skip:
@@ -122,7 +120,7 @@ async def write_stored_links(
uri,
MemoryFileUtils.write(mf),
ctx=ctx,
- **lock_kwargs,
+ lease_ref=lease_ref,
)
updated_uris.append(uri)
except Exception as e:
@@ -130,7 +128,6 @@ async def write_stored_links(
return updated_uris
-
def _remap_link_dict(link: Dict[str, Any], uri_remap: Dict[str, str]) -> Dict[str, Any]:
remapped = dict(link or {})
if remapped.get("from_uri") in uri_remap:
@@ -152,6 +149,7 @@ def remap_stored_links(links: List[StoredLink], uri_remap: Dict[str, str]) -> Li
remapped_links.append(link.model_copy(update={"from_uri": from_uri, "to_uri": to_uri}))
return remapped_links
+
def _operation_trace_id(op: ResolvedOperation) -> str | None:
source = getattr(op, "source", None)
trace_id = getattr(source, "trace_id", None) if source else None
@@ -293,6 +291,7 @@ class ExtractContext:
def get_year(self, ranges_str: str) -> str:
"""根据 ranges 字符串获取第一条消息的年份,fallback 到当前年份"""
from datetime import datetime
+
if not ranges_str:
return str(datetime.now().year)
msg_range = self.read_message_ranges(ranges_str)
@@ -304,6 +303,7 @@ class ExtractContext:
def get_month(self, ranges_str: str) -> str:
"""根据 ranges 字符串获取第一条消息的月份,fallback 到当前月份"""
from datetime import datetime
+
if not ranges_str:
return f"{datetime.now().month:02d}"
msg_range = self.read_message_ranges(ranges_str)
@@ -315,6 +315,7 @@ class ExtractContext:
def get_day(self, ranges_str: str) -> str:
"""根据 ranges 字符串获取第一条消息的日期,fallback 到当前日期"""
from datetime import datetime
+
if not ranges_str:
return f"{datetime.now().day:02d}"
msg_range = self.read_message_ranges(ranges_str)
@@ -711,8 +712,12 @@ class MemoryUpdater:
"""
def __init__(
- self, registry: Optional[MemoryTypeRegistry] = None, vikingdb=None, transaction_handle=None
+ self,
+ registry: Optional[MemoryTypeRegistry] = None,
+ vikingdb=None,
+ transaction_handle: Any = None,
):
+ """Create a memory updater with an optional pathlock transaction handle."""
self._viking_fs = None
self._registry = registry
self._vikingdb = vikingdb
@@ -846,6 +851,7 @@ class MemoryUpdater:
resolved_op,
ctx,
extract_context=extract_context,
+ lease_ref=self._transaction_handle,
)
# Add all uris to result (uris is List[str])
if resolved_op.is_edit():
@@ -866,7 +872,12 @@ class MemoryUpdater:
list(getattr(operations, "resolved_links", []) or []),
dict(getattr(operations, "delete_replacements", {}) or {}),
)
- await self._inherit_deleted_link_relations(operations, result, ctx)
+ await self._inherit_deleted_link_relations(
+ operations,
+ result,
+ ctx,
+ lease_ref=self._transaction_handle,
+ )
# Apply delete operations (delete_file_contents is List[MemoryFile])
# Skip deletes whose URI was just written in the same batch — this happens when the
@@ -896,13 +907,13 @@ class MemoryUpdater:
)
continue
try:
- await self._apply_delete(delete_uri, ctx)
+ await self._apply_delete(delete_uri, ctx, lease_ref=self._transaction_handle)
result.add_deleted(delete_uri)
except Exception as e:
tracer.error(f"Failed to delete memory {delete_uri}", e)
result.add_error(delete_uri, e)
- await self._sync_resource_refs_for_result(result, ctx)
+ await self._sync_resource_refs_for_result(result, ctx, lease_ref=self._transaction_handle)
# Vectorize written and edited memories
uri_memory_type_map = {}
@@ -923,6 +934,7 @@ class MemoryUpdater:
result,
ctx,
deleted_uris=set(result.deleted_uris),
+ lease_ref=self._transaction_handle,
)
tracer.info(f"Memory operations applied: {result.summary()}")
@@ -943,7 +955,13 @@ class MemoryUpdater:
)
for dir, memory_type in dirs.items():
- await self.generate_overview(memory_type, dir, ctx, extract_context)
+ await self.generate_overview(
+ memory_type,
+ dir,
+ ctx,
+ extract_context,
+ lease_ref=self._transaction_handle,
+ )
return result
@@ -951,6 +969,7 @@ class MemoryUpdater:
self,
result: MemoryUpdateResult,
ctx: RequestContext,
+ lease_ref: Any = None,
) -> None:
"""Synchronize resource refs for memory files touched by session extraction."""
viking_fs = self._get_viking_fs()
@@ -974,13 +993,17 @@ class MemoryUpdater:
uri,
MemoryFileUtils.write(mf),
ctx=ctx,
- lock_handle=self._transaction_handle,
+ lease_ref=lease_ref,
)
except Exception as exc:
logger.warning("Failed to sync resource refs for %s: %s", uri, exc)
async def _apply_upsert(
- self, resolved_op: ResolvedOperation, ctx: RequestContext, extract_context: Any = None
+ self,
+ resolved_op: ResolvedOperation,
+ ctx: RequestContext,
+ extract_context: Any = None,
+ lease_ref: Any = None,
):
"""Apply upsert operation from a flat model."""
viking_fs = self._get_viking_fs()
@@ -1096,7 +1119,7 @@ class MemoryUpdater:
uri,
new_full_content,
ctx=ctx,
- lock_handle=self._transaction_handle,
+ lease_ref=lease_ref,
)
def _distribute_links_to_operations(self, operations: ResolvedOperations) -> None:
@@ -1133,6 +1156,7 @@ class MemoryUpdater:
result: MemoryUpdateResult,
ctx: RequestContext,
deleted_uris: Optional[set[str]] = None,
+ lease_ref: Any = None,
) -> None:
"""Apply links to endpoint files that are NOT in the current upsert batch."""
viking_fs = self._get_viking_fs()
@@ -1153,15 +1177,15 @@ class MemoryUpdater:
ctx,
viking_fs,
skip_uris=skip,
- lock_handle=self._transaction_handle,
+ lease_ref=lease_ref,
)
-
async def _inherit_deleted_link_relations(
self,
operations: ResolvedOperations,
result: MemoryUpdateResult,
ctx: RequestContext,
+ lease_ref: Any = None,
) -> None:
uri_remap = dict(getattr(operations, "delete_replacements", {}) or {})
if not uri_remap:
@@ -1179,7 +1203,9 @@ class MemoryUpdater:
try:
content = await viking_fs.read_file(deleted_uri, ctx=ctx)
except Exception as e:
- tracer.error(f"Failed to read deleted memory links for replacement {deleted_uri}: {e}")
+ tracer.error(
+ f"Failed to read deleted memory links for replacement {deleted_uri}: {e}"
+ )
continue
if not content:
continue
@@ -1236,22 +1262,25 @@ class MemoryUpdater:
uri,
MemoryFileUtils.write(mf),
ctx=ctx,
- lock_handle=self._transaction_handle,
+ lease_ref=lease_ref,
)
result.add_edited(uri)
except Exception as e:
tracer.error(f"Failed to inherit deleted memory links for {uri}: {e}")
- async def _apply_delete(self, uri: str, ctx: RequestContext) -> None:
+ async def _apply_delete(
+ self,
+ uri: str,
+ ctx: RequestContext,
+ lease_ref: Any = None,
+ ) -> None:
"""Apply delete operation (uri is already a string)."""
viking_fs = self._get_viking_fs()
# Delete from VikingFS
- # VikingFS automatically handles vector index cleanup
- # Pass transaction_handle so rm() reuses the compressor's tree lock
- # instead of trying to acquire a new lock (which would conflict).
+ # VikingFS automatically handles vector index cleanup.
try:
- await viking_fs.rm(uri, recursive=False, ctx=ctx, lock_handle=self._transaction_handle)
+ await viking_fs.rm(uri, recursive=False, ctx=ctx, lease_ref=lease_ref)
except NotFoundError:
tracer.error(f"Memory not found for delete: {uri}")
# Idempotent - deleting non-existent file succeeds
@@ -1397,6 +1426,7 @@ class MemoryUpdater:
directory: str,
ctx: RequestContext,
extract_context: Any = None,
+ lease_ref: Any = None,
) -> None:
"""
Generate .overview.md file for a directory based on overview_template.
@@ -1453,7 +1483,7 @@ class MemoryUpdater:
overview_path,
recursive=False,
ctx=ctx,
- lock_handle=self._transaction_handle,
+ lease_ref=lease_ref,
)
except Exception:
pass
@@ -1464,7 +1494,7 @@ class MemoryUpdater:
directory,
recursive=True,
ctx=ctx,
- lock_handle=self._transaction_handle,
+ lease_ref=lease_ref,
)
except Exception:
pass
@@ -1519,7 +1549,7 @@ class MemoryUpdater:
overview_path,
rendered,
ctx=ctx,
- lock_handle=self._transaction_handle,
+ lease_ref=lease_ref,
)
except Exception as e:
tracer.error(f"Failed to write overview {overview_path}: {e}")
diff --git a/openviking/session/memory/streaming_memory_updater.py b/openviking/session/memory/streaming_memory_updater.py
index 540cc1432..4453463f0 100644
--- a/openviking/session/memory/streaming_memory_updater.py
+++ b/openviking/session/memory/streaming_memory_updater.py
@@ -442,7 +442,6 @@ class StreamingMemoryUpdater:
updater = MemoryUpdater(
registry=self.registry,
vikingdb=self.vikingdb,
- transaction_handle=None,
)
extract_context = ExtractContext(messages)
isolation_handler = _make_isolation_handler(request, extract_context)
diff --git a/openviking/session/session.py b/openviking/session/session.py
index 80ec7f356..9347ef2fd 100644
--- a/openviking/session/session.py
+++ b/openviking/session/session.py
@@ -698,8 +698,8 @@ class Session:
await self._viking_fs.write_file(f"{self._session_uri}/messages.jsonl", "", ctx=self.ctx)
await self._save_meta()
- async def _save_meta(self) -> None:
- """Persist .meta.json to storage."""
+ async def _save_meta(self, lease_ref: Optional[Any] = None) -> None:
+ """Persist .meta.json to storage using an optional held PathLock lease."""
if not self._viking_fs:
return
self._meta.updated_at = get_current_timestamp()
@@ -707,6 +707,7 @@ class Session:
uri=f"{self._session_uri}/.meta.json",
content=json.dumps(self._meta.to_dict(), ensure_ascii=False),
ctx=self.ctx,
+ lease_ref=lease_ref,
)
@property
@@ -1125,15 +1126,11 @@ class Session:
await self._append_messages_without_path_lock(messages)
return
- from openviking.storage.transaction import LockContext, get_lock_manager
-
session_path = uri_to_path(self._session_uri, ctx=self.ctx)
- async with LockContext(
- get_lock_manager(),
- [session_path],
- lock_mode="exact",
- timeout=_SESSION_PHASE1_LOCK_TIMEOUT_SECONDS,
- ):
+ lease = await self._viking_fs._async_agfs.pathlock_acquire_tree(
+ session_path, timeout_secs=_SESSION_PHASE1_LOCK_TIMEOUT_SECONDS
+ )
+ try:
self._messages = await self._read_live_messages_strict()
in_memory_meta = self._meta
try:
@@ -1153,8 +1150,11 @@ class Session:
f"{self._session_uri}/messages.jsonl",
batch_content,
ctx=self.ctx,
+ lease_ref=lease,
)
- await self._save_meta()
+ await self._save_meta(lease_ref=lease)
+ finally:
+ await self._viking_fs._async_agfs.pathlock_release(lease)
async def _append_messages_without_path_lock(self, messages: List[Message]) -> None:
"""Compatibility append for storage adapters without path locking."""
@@ -1420,7 +1420,12 @@ class Session:
self._meta.retained_message_token_budget = retained_message_token_budget
self._meta.min_raw_tail_steps = min_raw_tail_steps
- async def _merge_archive_meta(self, archive_uri: str, updates: Dict[str, Any]) -> None:
+ async def _merge_archive_meta(
+ self,
+ archive_uri: str,
+ updates: Dict[str, Any],
+ lease_ref: Optional[Any] = None,
+ ) -> None:
"""Merge archive metadata so Phase 2 cannot erase Phase 1 planning data."""
if not self._viking_fs:
return
@@ -1441,6 +1446,7 @@ class Session:
uri=f"{archive_uri}/.meta.json",
content=json.dumps(meta, ensure_ascii=False),
ctx=self.ctx,
+ lease_ref=lease_ref,
)
@staticmethod
@@ -1479,6 +1485,7 @@ class Session:
min_raw_tail_steps: int,
agent_evolution_enabled: bool = True,
agent_memory_skip_reason: Optional[str] = None,
+ lease_ref: Optional[Any] = None,
) -> None:
"""Persist the Phase 1 intent before any destructive root rewrite."""
payload = {
@@ -1504,9 +1511,15 @@ class Session:
"skip_reason": agent_memory_skip_reason,
},
},
+ lease_ref=lease_ref,
)
- async def _write_phase1_ready_marker(self, archive_uri: str) -> None:
+ async def _write_phase1_ready_marker(
+ self,
+ archive_uri: str,
+ lease_ref: Optional[Any] = None,
+ ) -> None:
+ """Persist that Phase 1 is ready using an optional held PathLock lease."""
phase1 = await self._read_phase1_meta(archive_uri)
phase1.update(
{
@@ -1514,7 +1527,7 @@ class Session:
"ready_at": get_current_timestamp(),
}
)
- await self._merge_archive_meta(archive_uri, {"phase1": phase1})
+ await self._merge_archive_meta(archive_uri, {"phase1": phase1}, lease_ref=lease_ref)
async def _archive_file_exists(self, archive_uri: str, file_name: str) -> bool:
try:
@@ -1544,15 +1557,11 @@ class Session:
if await self._archive_file_exists(archive_uri, ".failed.json"):
return False
- from openviking.storage.transaction import LockContext, get_lock_manager
-
session_path = self._viking_fs._uri_to_path(self._session_uri, ctx=self.ctx)
- async with LockContext(
- get_lock_manager(),
- [session_path],
- lock_mode="exact",
- timeout=_SESSION_PHASE1_LOCK_TIMEOUT_SECONDS,
- ):
+ lease = await self._viking_fs._async_agfs.pathlock_acquire_tree(
+ session_path, timeout_secs=_SESSION_PHASE1_LOCK_TIMEOUT_SECONDS
+ )
+ try:
marker = await self._read_phase1_meta(archive_uri)
if marker.get("status") == "ready":
return True
@@ -1574,20 +1583,21 @@ class Session:
archive_uri,
stage="phase1_recovery",
error=f"Cannot verify Phase 1 state: {exc}",
+ lease_ref=lease,
)
return False
live_ids = [message.id for message in live_messages]
archived_only_ids = set(archived_ids) - set(retained_ids)
- phase1_applied = (
- live_ids[: len(retained_ids)] == retained_ids
- and not archived_only_ids.intersection(live_ids)
- )
+ phase1_applied = live_ids[
+ : len(retained_ids)
+ ] == retained_ids and not archived_only_ids.intersection(live_ids)
if not phase1_applied:
await self._write_failed_marker(
archive_uri,
stage="phase1_recovery",
error="Root rewrite was not durably completed before process interruption",
+ lease_ref=lease,
)
return False
@@ -1605,9 +1615,7 @@ class Session:
self._remember_retention_policy(
keep_recent_count=max(0, int(marker.get("keep_recent_count", 0) or 0)),
retention_mode=str(marker.get("retention_mode", "") or "") or None,
- keep_recent_turn_count=max(
- 0, int(marker.get("keep_recent_turn_count", 0) or 0)
- ),
+ keep_recent_turn_count=max(0, int(marker.get("keep_recent_turn_count", 0) or 0)),
retained_message_token_budget=max(
0, int(marker.get("retained_message_token_budget", 0) or 0)
),
@@ -1620,10 +1628,12 @@ class Session:
)
self._meta.last_commit_at = get_current_timestamp()
self._rebuild_pending_tokens()
- await self._save_meta()
- await self._write_phase1_ready_marker(archive_uri)
+ await self._save_meta(lease_ref=lease)
+ await self._write_phase1_ready_marker(archive_uri, lease_ref=lease)
logger.warning("Recovered interrupted Session Phase 1: %s", archive_uri)
return True
+ finally:
+ await self._viking_fs._async_agfs.pathlock_release(lease)
def commit(
self,
@@ -1679,7 +1689,6 @@ class Session:
from openviking.service.task_tracker import get_task_tracker
from openviking.storage.queuefs import QueueManager, get_queue_manager
from openviking.storage.queuefs.session_commit_msg import SessionCommitMsg
- from openviking.storage.transaction import LockContext, get_lock_manager
trace_id = tracer.get_trace_id()
keep_recent_count = max(0, int(keep_recent_count or 0))
@@ -1739,12 +1748,10 @@ class Session:
# can hold stale Session objects, so in-memory emptiness is never a
# correctness boundary.
session_path = self._viking_fs._uri_to_path(self._session_uri, ctx=self.ctx)
- async with LockContext(
- get_lock_manager(),
- [session_path],
- lock_mode="exact",
- timeout=_SESSION_PHASE1_LOCK_TIMEOUT_SECONDS,
- ):
+ lease = await self._viking_fs._async_agfs.pathlock_acquire_tree(
+ session_path, timeout_secs=_SESSION_PHASE1_LOCK_TIMEOUT_SECONDS
+ )
+ try:
self._messages = await self._read_live_messages_strict()
try:
meta_content = await self._viking_fs.read_file(
@@ -1796,7 +1803,7 @@ class Session:
retained_message_token_budget=effective_token_budget if turn_mode else 0,
min_raw_tail_steps=effective_min_tail,
)
- await self._save_meta()
+ await self._save_meta(lease_ref=lease)
get_current_telemetry().set("memory.extracted", 0)
return {
"session_id": self.session_id,
@@ -1836,7 +1843,7 @@ class Session:
# remember the policy for subsequent add_message accounting.
if not messages_to_archive:
self._messages = retained_messages
- await self._write_to_agfs_async(messages=self._messages)
+ await self._write_to_agfs_async(messages=self._messages, lease_ref=lease)
self._meta.pending_tokens = 0
self._meta.message_count = total
self._remember_retention_policy(
@@ -1846,7 +1853,7 @@ class Session:
retained_message_token_budget=effective_token_budget if turn_mode else 0,
min_raw_tail_steps=effective_min_tail,
)
- await self._save_meta()
+ await self._save_meta(lease_ref=lease)
get_current_telemetry().set("memory.extracted", 0)
return {
"session_id": self.session_id,
@@ -1897,6 +1904,7 @@ class Session:
min_raw_tail_steps=effective_min_tail,
agent_evolution_enabled=agent_evolution_enabled,
agent_memory_skip_reason=agent_memory_skip_reason,
+ lease_ref=lease,
)
# Archive raw remains durable and recoverable before any live
@@ -1907,6 +1915,7 @@ class Session:
uri=f"{archive_uri}/messages.jsonl",
content="\n".join(lines) + "\n",
ctx=self.ctx,
+ lease_ref=lease,
)
if retention_plan is not None:
await self._merge_archive_meta(
@@ -1919,6 +1928,7 @@ class Session:
min_raw_tail_steps=effective_min_tail,
)
},
+ lease_ref=lease,
)
phase1_stage = "queue_enqueue"
@@ -1943,7 +1953,7 @@ class Session:
phase1_stage = "phase1_persist"
self._messages = retained_messages
- await self._write_to_agfs_async(messages=self._messages)
+ await self._write_to_agfs_async(messages=self._messages, lease_ref=lease)
self._meta.message_count = len(self._messages)
self._meta.pending_tokens = 0
self._remember_retention_policy(
@@ -1958,8 +1968,8 @@ class Session:
self._compression.compression_index,
)
self._meta.last_commit_at = get_current_timestamp()
- await self._save_meta()
- await self._write_phase1_ready_marker(archive_uri)
+ await self._save_meta(lease_ref=lease)
+ await self._write_phase1_ready_marker(archive_uri, lease_ref=lease)
except Exception as e:
logger.error(f"[commit] Failed during {phase1_stage}: {e}")
# Whether the queue write failed or a queued Phase 1 stopped
@@ -1970,6 +1980,7 @@ class Session:
archive_uri,
stage=phase1_stage,
error=str(e),
+ lease_ref=lease,
)
except Exception:
logger.exception(
@@ -1979,6 +1990,8 @@ class Session:
self._messages = original_messages
self._compression.compression_index -= 1
raise
+ finally:
+ await self._viking_fs._async_agfs.pathlock_release(lease)
# Lock released; Phase 1 intent, queue item, retained root, metadata and
# ready metadata are all durable.
@@ -2098,23 +2111,17 @@ class Session:
# that temporarily stored this snapshot in the queue payload.
phase1 = archive_meta.get("phase1")
queue_snapshot = phase1.get("queue_message") if isinstance(phase1, dict) else None
- agent_evolution_snapshot = (
- queue_snapshot if isinstance(queue_snapshot, dict) else {}
- )
+ agent_evolution_snapshot = queue_snapshot if isinstance(queue_snapshot, dict) else {}
snapshot_enabled = agent_evolution_snapshot.get("enabled")
if snapshot_enabled is None:
snapshot_enabled = agent_evolution_snapshot.get("agent_evolution_enabled")
# Archives created before this setting existed preserve their original
# behavior, where Agent memory extraction was enabled by default.
- agent_evolution_enabled = (
- snapshot_enabled if isinstance(snapshot_enabled, bool) else True
- )
+ agent_evolution_enabled = snapshot_enabled if isinstance(snapshot_enabled, bool) else True
agent_memory_skip_reason = agent_evolution_snapshot.get("skip_reason")
if agent_memory_skip_reason is None:
- agent_memory_skip_reason = agent_evolution_snapshot.get(
- "agent_memory_skip_reason"
- )
+ agent_memory_skip_reason = agent_evolution_snapshot.get("agent_memory_skip_reason")
if agent_memory_skip_reason is None:
agent_memory_skip_reason = _agent_memory_skip_reason(
agent_evolution_enabled=agent_evolution_enabled,
@@ -2700,6 +2707,7 @@ class Session:
blocked_by: str = "",
skipped: bool = True,
completed_memory_steps: Optional[Dict[str, List[str]]] = None,
+ lease_ref: Optional[Any] = None,
) -> None:
"""Persist a terminal failure marker for the archive."""
if not self._viking_fs:
@@ -2717,6 +2725,7 @@ class Session:
uri=f"{archive_uri}/.failed.json",
content=json.dumps(payload, ensure_ascii=False),
ctx=self.ctx,
+ lease_ref=lease_ref,
)
async def get_session_context(self, token_budget: int = 128_000) -> Dict[str, Any]:
@@ -3387,9 +3396,7 @@ class Session:
continue
if not isinstance(abstract, str) or not abstract.strip():
continue
- valid_source_ids = [
- item for item in source_ids if isinstance(item, str) and item
- ]
+ valid_source_ids = [item for item in source_ids if isinstance(item, str) and item]
if not valid_source_ids:
continue
@@ -3407,9 +3414,7 @@ class Session:
)
seen_source_ids = set(candidate["source_message_ids"])
new_source_ids = [
- source_id
- for source_id in valid_source_ids
- if source_id not in seen_source_ids
+ source_id for source_id in valid_source_ids if source_id not in seen_source_ids
]
if not new_source_ids:
continue
@@ -3493,9 +3498,7 @@ class Session:
while True:
earlier_states = [
- state
- for state in await self._scan_archive_states()
- if state.index < archive_index
+ state for state in await self._scan_archive_states() if state.index < archive_index
]
pending_states = [state for state in earlier_states if state.state == "pending"]
if not pending_states:
@@ -3586,15 +3589,11 @@ class Session:
telemetry_snapshot: Any,
) -> None:
"""Merge Phase 2 results without overwriting concurrent root updates."""
- from openviking.storage.transaction import LockContext, get_lock_manager
-
session_path = self._viking_fs._uri_to_path(self._session_uri, ctx=self.ctx)
- async with LockContext(
- get_lock_manager(),
- [session_path],
- lock_mode="exact",
- timeout=_SESSION_PHASE1_LOCK_TIMEOUT_SECONDS,
- ):
+ lease = await self._viking_fs._async_agfs.pathlock_acquire_tree(
+ session_path, timeout_secs=_SESSION_PHASE1_LOCK_TIMEOUT_SECONDS
+ )
+ try:
latest_meta = self._meta
try:
meta_content = await self._viking_fs.read_file(
@@ -3628,7 +3627,9 @@ class Session:
latest_meta.last_commit_at = get_current_timestamp()
latest_meta.message_count = await self._read_live_message_count()
self._meta = latest_meta
- await self._save_meta()
+ await self._save_meta(lease_ref=lease)
+ finally:
+ await self._viking_fs._async_agfs.pathlock_release(lease)
async def _read_live_message_count(self) -> int:
"""Count current live session messages from persisted storage."""
@@ -4815,8 +4816,12 @@ class Session:
return "\n".join(parts).rstrip() + "\n"
- async def _write_to_agfs_async(self, messages: List[Message]) -> None:
- """Write messages.jsonl to AGFS (async)."""
+ async def _write_to_agfs_async(
+ self,
+ messages: List[Message],
+ lease_ref: Optional[Any] = None,
+ ) -> None:
+ """Write messages.jsonl to AGFS using an optional held PathLock lease."""
if not self._viking_fs:
return
@@ -4833,16 +4838,19 @@ class Session:
uri=f"{self._session_uri}/messages.jsonl",
content=content,
ctx=self.ctx,
+ lease_ref=lease_ref,
)
await viking_fs.write_file(
uri=f"{self._session_uri}/.abstract.md",
content=abstract,
ctx=self.ctx,
+ lease_ref=lease_ref,
)
await viking_fs.write_file(
uri=f"{self._session_uri}/.overview.md",
content=overview,
ctx=self.ctx,
+ lease_ref=lease_ref,
)
def _generate_abstract(self) -> str:
diff --git a/openviking/session/train/components/policy_updater.py b/openviking/session/train/components/policy_updater.py
index a43f3ac0e..897ac3ccf 100644
--- a/openviking/session/train/components/policy_updater.py
+++ b/openviking/session/train/components/policy_updater.py
@@ -130,9 +130,7 @@ class MemoryFilePolicyUpdater:
)
-def _apply_items_to_snapshot(
- items: list[PolicyPlanItem], policy_set: PolicySet
-) -> PolicySet:
+def _apply_items_to_snapshot(items: list[PolicyPlanItem], policy_set: PolicySet) -> PolicySet:
policies_by_uri = {policy.uri: policy for policy in policy_set.policies}
result = list(policy_set.policies)
@@ -225,7 +223,6 @@ def _target_uri(item: PolicyPlanItem, root_uri: str) -> str:
return f"{root_uri.rstrip('/')}/{_safe_experience_filename(item.target_name)}.md"
-
def _plan_to_resolved_operations(
*,
plan: PolicyUpdatePlan,
@@ -247,8 +244,7 @@ def _plan_to_resolved_operations(
!= _normalize_guard_content(item.before_content)
):
errors.append(
- "base content mismatch for "
- f"{item.target_name}: expected gradient before_content"
+ f"base content mismatch for {item.target_name}: expected gradient before_content"
)
continue
@@ -264,9 +260,7 @@ def _plan_to_resolved_operations(
updated = _find_policy(updated_policy_set, uri=uri, name=item.target_name)
if updated is None:
- errors.append(
- f"planned policy not found after simulation: {item.target_name}"
- )
+ errors.append(f"planned policy not found after simulation: {item.target_name}")
continue
upserts.append(
diff --git a/openviking/session/train/components/skill_policy_updater.py b/openviking/session/train/components/skill_policy_updater.py
index 2bea52390..500341840 100644
--- a/openviking/session/train/components/skill_policy_updater.py
+++ b/openviking/session/train/components/skill_policy_updater.py
@@ -101,7 +101,7 @@ class SkillPolicyUpdater:
continue
try:
skill_root = _root_uri_from_skill_md(old_file.uri)
- await viking_fs.rm(skill_root, ctx=ctx, lock_handle=transaction_handle)
+ await viking_fs.rm(skill_root, ctx=ctx, lease_ref=transaction_handle)
deleted_uris.append(old_file.uri)
except Exception as exc:
delete_errors.append(f"{old_file.uri}: {exc}")
@@ -138,9 +138,7 @@ def _coerce_request_context(context: Any) -> RequestContext | None:
return None
-def _apply_items_to_snapshot(
- items: list[PolicyPlanItem], policy_set: PolicySet
-) -> PolicySet:
+def _apply_items_to_snapshot(items: list[PolicyPlanItem], policy_set: PolicySet) -> PolicySet:
policies_by_uri = {policy.uri: policy for policy in policy_set.policies}
result = list(policy_set.policies)
@@ -239,9 +237,7 @@ def _plan_to_resolved_operations(
updated = _find_policy(updated_policy_set, uri=uri, name=item.target_name)
if updated is None:
- errors.append(
- f"planned skill policy not found after simulation: {item.target_name}"
- )
+ errors.append(f"planned skill policy not found after simulation: {item.target_name}")
continue
old_mf = _policy_to_memory_file(current) if current is not None else None
diff --git a/openviking/session/train/domain.py b/openviking/session/train/domain.py
index b7348952c..6e66158bf 100644
--- a/openviking/session/train/domain.py
+++ b/openviking/session/train/domain.py
@@ -80,19 +80,12 @@ class PolicySet:
if uri_to_path is None:
raise RuntimeError("PolicySet.viking_fs must provide _uri_to_path for locking")
- from openviking.storage.transaction import get_lock_manager
-
- lock_manager = get_lock_manager()
- handle = lock_manager.create_handle()
path = uri_to_path(self.root_uri, ctx=self.request_context)
- acquired = await lock_manager.acquire_tree(handle, path, timeout=None)
- if not acquired:
- await lock_manager.release(handle)
- raise RuntimeError(f"Failed to acquire policy tree lock for {self.root_uri}")
+ lease = await self.viking_fs._async_agfs.pathlock_acquire_tree(path, timeout_secs=300.0)
try:
- yield handle
+ yield lease
finally:
- await lock_manager.release(handle)
+ await self.viking_fs._async_agfs.pathlock_release(lease)
async def reload(self) -> "PolicySet":
"""Reload this policy set from its backing VikingFS under the same ctx."""
diff --git a/openviking/storage/content_write.py b/openviking/storage/content_write.py
index 304eea4c6..6a4a776ce 100644
--- a/openviking/storage/content_write.py
+++ b/openviking/storage/content_write.py
@@ -9,7 +9,7 @@ import binascii
import hashlib
import os
from collections import defaultdict
-from typing import TYPE_CHECKING, Any, Dict, Optional
+from typing import Any, Dict, Optional
from openviking.core.namespace import (
NamespaceShapeError,
@@ -27,10 +27,9 @@ from openviking.session.memory.utils.resource_refs import (
RESOURCE_REF_SOURCE_CONTENT_WRITE,
sync_memory_resource_refs,
)
-from openviking.storage.errors import ResourceBusyError
+from openviking.storage.errors import LockAcquisitionError, ResourceBusyError
from openviking.storage.queuefs import SemanticMsg, get_queue_manager
from openviking.storage.queuefs.semantic_msg import build_semantic_coalesce_key
-from openviking.storage.transaction import get_lock_manager
from openviking.storage.viking_fs import VikingFS
from openviking.telemetry import get_current_telemetry
from openviking.telemetry.request_wait_tracker import get_request_wait_tracker
@@ -51,12 +50,19 @@ from openviking_cli.utils.logger import get_logger
logger = get_logger(__name__)
-if TYPE_CHECKING:
- from openviking.storage.transaction.lock_handle import LockHandle
-
_DERIVED_FILENAMES = frozenset({".abstract.md", ".overview.md", ".relations.json"})
_CREATE_ALLOWED_EXTENSIONS = frozenset(
- {".md", ".txt", ".json", ".yaml", ".yml", ".toml", ".py", ".js", ".ts"}
+ {
+ ".md",
+ ".txt",
+ ".json",
+ ".yaml",
+ ".yml",
+ ".toml",
+ ".py",
+ ".js",
+ ".ts",
+ }
)
_BATCH_MAX_OPERATIONS = 128
_BATCH_MAX_FILE_BYTES = 8 * 1024 * 1024
@@ -154,16 +160,14 @@ class ContentWriteCoordinator:
normalized_root, operations, ctx=ctx
)
- lock_manager = get_lock_manager()
- handle = lock_manager.create_handle()
root_path = self._viking_fs._uri_to_path(normalized_root, ctx=ctx)
- acquired = await lock_manager.acquire_tree(handle, root_path)
- if not acquired:
- await lock_manager.release(handle)
+ try:
+ lease = await self._viking_fs._async_agfs.pathlock_acquire_tree(root_path)
+ except LockAcquisitionError as exc:
raise ResourceBusyError(
f"resource is busy and cannot be written now: {normalized_root}",
uri=normalized_root,
- )
+ ) from exc
created: list[str] = []
updated: list[str] = []
@@ -226,7 +230,7 @@ class ContentWriteCoordinator:
uri,
operation["content"],
ctx=ctx,
- lock_handle=handle,
+ lease_ref=lease,
)
except Exception as exc:
write_error = exc
@@ -238,7 +242,7 @@ class ContentWriteCoordinator:
created.append(uri)
refresh_kinds[uri] = "added"
finally:
- await lock_manager.release(handle)
+ await self._viking_fs._async_agfs.pathlock_release(lease)
lock_released = True
assert lock_released
@@ -689,16 +693,14 @@ class ContentWriteCoordinator:
written_bytes: int,
telemetry_id: str,
) -> Dict[str, Any]:
- lock_manager = get_lock_manager()
- handle = lock_manager.create_handle()
lock_path = self._viking_fs._uri_to_path(uri, ctx=ctx)
- acquired = await lock_manager.acquire_exact_path(handle, lock_path)
- if not acquired:
- await lock_manager.release(handle)
+ try:
+ lease = await self._viking_fs._async_agfs.pathlock_acquire_exact(lock_path)
+ except LockAcquisitionError as exc:
raise ResourceBusyError(
f"resource is busy and cannot be written now: {uri}",
uri=uri,
- )
+ ) from exc
previous_content: Optional[str] = None
content_written = False
@@ -709,13 +711,7 @@ class ContentWriteCoordinator:
previous_content = await self._viking_fs.read_file(uri, ctx=ctx)
if wait and telemetry_id:
get_request_wait_tracker().register_request(telemetry_id)
- await self._write_in_place(
- uri,
- content,
- mode=mode,
- ctx=ctx,
- lock_handle=handle,
- )
+ await self._write_in_place(uri, content, mode=mode, ctx=ctx, lease_ref=lease)
content_written = True
await self._enqueue_semantic_refresh(
root_uri=root_uri,
@@ -725,7 +721,7 @@ class ContentWriteCoordinator:
change_type="added" if mode == "create" else "modified",
)
semantic_enqueued = True
- await lock_manager.release(handle)
+ await self._viking_fs._async_agfs.pathlock_release(lease)
lock_released = True
queue_status = (
await self._wait_for_request(telemetry_id=telemetry_id, timeout=timeout)
@@ -748,10 +744,10 @@ class ContentWriteCoordinator:
previous_content=previous_content,
mode=mode,
ctx=ctx,
- lock_handle=handle,
+ lease_ref=lease,
)
if not lock_released:
- await lock_manager.release(handle)
+ await self._viking_fs._async_agfs.pathlock_release(lease)
raise
finally:
if wait and telemetry_id:
@@ -764,18 +760,18 @@ class ContentWriteCoordinator:
previous_content: Optional[str],
mode: str,
ctx: RequestContext,
- lock_handle: Any,
+ lease_ref: Optional[Dict[str, Any]] = None,
) -> None:
try:
if mode == "create":
- await self._viking_fs.rm(uri, ctx=ctx, lock_handle=lock_handle)
+ await self._viking_fs.rm(uri, ctx=ctx, lease_ref=lease_ref)
return
if previous_content is not None:
await self._viking_fs.write_file(
uri,
previous_content,
ctx=ctx,
- lock_handle=lock_handle,
+ lease_ref=lease_ref,
)
except Exception:
logger.error("Failed to rollback direct content write for %s", uri, exc_info=True)
@@ -885,7 +881,7 @@ class ContentWriteCoordinator:
*,
mode: str,
ctx: RequestContext,
- lock_handle: Optional["LockHandle"] = None,
+ lease_ref: Optional[Dict[str, Any]] = None,
) -> None:
if context_type_for_uri(uri) == "memory":
if mode == "replace":
@@ -903,7 +899,7 @@ class ContentWriteCoordinator:
uri,
MemoryFileUtils.write(mf),
ctx=ctx,
- lock_handle=lock_handle,
+ lease_ref=lease_ref,
)
return
@@ -912,14 +908,9 @@ class ContentWriteCoordinator:
mf = MemoryFileUtils.read(existing_raw, uri=uri)
mf.content = mf.content + content
updated_raw = MemoryFileUtils.write(mf)
- await self._viking_fs.write_file(
- uri,
- updated_raw,
- ctx=ctx,
- lock_handle=lock_handle,
- )
+ await self._viking_fs.write_file(uri, updated_raw, ctx=ctx, lease_ref=lease_ref)
return
- await self._viking_fs.write_file(uri, content, ctx=ctx, lock_handle=lock_handle)
+ await self._viking_fs.write_file(uri, content, ctx=ctx, lease_ref=lease_ref)
async def _enqueue_semantic_refresh(
self,
@@ -977,28 +968,20 @@ class ContentWriteCoordinator:
written_bytes: int,
telemetry_id: str,
) -> Dict[str, Any]:
- lock_manager = get_lock_manager()
- handle = lock_manager.create_handle()
lock_path = self._viking_fs._uri_to_path(uri, ctx=ctx)
- acquired = await lock_manager.acquire_exact_path(handle, lock_path)
- if not acquired:
- await lock_manager.release(handle)
+ try:
+ lease = await self._viking_fs._async_agfs.pathlock_acquire_exact(lock_path)
+ except LockAcquisitionError as exc:
raise ResourceBusyError(
f"resource is busy and cannot be written now: {uri}",
uri=uri,
- )
+ ) from exc
released = False
request_registered = False
try:
- await self._write_in_place(
- uri,
- content,
- mode=mode,
- ctx=ctx,
- lock_handle=handle,
- )
- await lock_manager.release(handle)
+ await self._write_in_place(uri, content, mode=mode, ctx=ctx, lease_ref=lease)
+ await self._viking_fs._async_agfs.pathlock_release(lease)
released = True
if wait and telemetry_id and self._vikingdb_has_queue():
get_request_wait_tracker().register_request(telemetry_id)
@@ -1041,7 +1024,7 @@ class ContentWriteCoordinator:
)
except Exception:
if not released:
- await lock_manager.release(handle)
+ await self._viking_fs._async_agfs.pathlock_release(lease)
raise
finally:
if request_registered:
diff --git a/openviking/storage/observers/__init__.py b/openviking/storage/observers/__init__.py
index b95548026..841cd7144 100644
--- a/openviking/storage/observers/__init__.py
+++ b/openviking/storage/observers/__init__.py
@@ -2,7 +2,6 @@
# SPDX-License-Identifier: AGPL-3.0
from .base_observer import BaseObserver
from .filesystem_observer import FilesystemObserver
-from .lock_observer import LockObserver
from .models_observer import ModelsObserver
from .queue_observer import QueueObserver
from .retrieval_observer import RetrievalObserver
@@ -11,7 +10,6 @@ from .vikingdb_observer import VikingDBObserver
__all__ = [
"BaseObserver",
"FilesystemObserver",
- "LockObserver",
"ModelsObserver",
"QueueObserver",
"RetrievalObserver",
diff --git a/openviking/storage/observers/lock_observer.py b/openviking/storage/observers/lock_observer.py
deleted file mode 100644
index 1e7bc5e81..000000000
--- a/openviking/storage/observers/lock_observer.py
+++ /dev/null
@@ -1,74 +0,0 @@
-# Copyright (c) 2026 Beijing Volcano Engine Technology Co., Ltd.
-# SPDX-License-Identifier: AGPL-3.0
-"""LockObserver: Lock system observability."""
-
-import time
-from typing import Any, Dict, List
-
-from openviking.storage.observers.base_observer import BaseObserver
-from openviking.storage.transaction.lock_manager import LockManager
-from openviking_cli.utils.logger import get_logger
-
-logger = get_logger(__name__)
-
-
-class LockObserver(BaseObserver):
- """Observability tool for the lock system."""
-
- def __init__(self, lock_manager: LockManager):
- self._manager = lock_manager
-
- def get_active_locks(self) -> List[Dict[str, Any]]:
- """Return info about every active lock handle."""
- now = time.time()
- return [
- {
- "id": h.id,
- "lock_count": len(h.locks),
- "created_at": h.created_at,
- "last_active_at": h.last_active_at,
- "duration_seconds": round(now - h.created_at, 1),
- "idle_seconds": round(now - h.last_active_at, 1),
- }
- for h in self._manager.get_active_handles().values()
- ]
-
- def get_hanging_locks(self, threshold: float = 600) -> List[Dict[str, Any]]:
- """Return locks that have been idle longer than *threshold* seconds."""
- return [lock for lock in self.get_active_locks() if lock["idle_seconds"] > threshold]
-
- # ------ BaseObserver interface ------
-
- def get_status_table(self) -> str:
- locks = self.get_active_locks()
- if not locks:
- return "No active locks."
-
- from tabulate import tabulate
-
- data = [
- {
- "Handle ID": l["id"][:8] + "...",
- "Locks": l["lock_count"],
- "Duration": f"{l['duration_seconds']}s",
- "Idle": f"{l['idle_seconds']}s",
- "Created": time.strftime("%H:%M:%S", time.localtime(l["created_at"])),
- }
- for l in locks
- ]
- data.append(
- {
- "Handle ID": f"TOTAL ({len(locks)})",
- "Locks": sum(l["lock_count"] for l in locks),
- "Duration": "",
- "Idle": "",
- "Created": "",
- }
- )
- return tabulate(data, headers="keys", tablefmt="pretty")
-
- def is_healthy(self) -> bool:
- return not self.get_hanging_locks(600)
-
- def has_errors(self) -> bool:
- return bool(self.get_hanging_locks(600))
diff --git a/openviking/storage/queuefs/add_resource_processor.py b/openviking/storage/queuefs/add_resource_processor.py
index 05fb0edbf..771c2102b 100644
--- a/openviking/storage/queuefs/add_resource_processor.py
+++ b/openviking/storage/queuefs/add_resource_processor.py
@@ -29,21 +29,19 @@ class AddResourceProcessor(DequeueHandlerBase):
resource_service: Any,
service_loop: asyncio.AbstractEventLoop,
queue_name: str,
+ viking_fs: Any,
):
self._resource_service = resource_service
self._service_loop = service_loop
self._queue_name = queue_name
+ self._viking_fs = viking_fs
async def _load_lock(self, msg: AddResourceMsg, ctx: RequestContext) -> Any:
+ """Adopt a pathlock handoff ref, returning an owned lease dict."""
if msg.lock_handoff is None:
return None
- from openviking.storage.transaction.lock_lease import LockHandoffRef, OwnedLockLease
-
- ref = LockHandoffRef.from_value(msg.lock_handoff)
- if ref is None:
- raise ValueError("Invalid lock_handoff")
try:
- return await OwnedLockLease.from_handoff(ref)
+ return await self._viking_fs._async_agfs.pathlock_adopt(msg.lock_handoff)
except Exception as handoff_error:
try:
return await self._resource_service.reacquire_add_resource_job_lock(
@@ -179,7 +177,7 @@ class AddResourceProcessor(DequeueHandlerBase):
finally:
with suppress(Exception):
if resource_lock is not None:
- await resource_lock.close()
+ await self._viking_fs._async_agfs.pathlock_release(resource_lock)
async def on_dequeue(self, data: Optional[Dict[str, Any]]) -> Optional[Dict[str, Any]]:
if not data:
diff --git a/openviking/storage/queuefs/semantic_dag.py b/openviking/storage/queuefs/semantic_dag.py
index 5e2179918..07ad10faa 100644
--- a/openviking/storage/queuefs/semantic_dag.py
+++ b/openviking/storage/queuefs/semantic_dag.py
@@ -5,13 +5,12 @@
import asyncio
import threading
from dataclasses import dataclass, field
-from typing import ClassVar, Dict, List, Optional, Set
+from typing import Any, ClassVar, Dict, List, Optional, Set
from weakref import WeakKeyDictionary
from openviking.utils.ingest_options import IngestOptions
from openviking.server.identity import RequestContext
from openviking.storage.queuefs.semantic_sidecar import write_semantic_sidecars
-from openviking.storage.transaction import NO_LOCK, LockLease
from openviking.storage.viking_fs import LS_ALL_NODES, get_viking_fs
from openviking.telemetry.request_wait_tracker import get_request_wait_tracker
from openviking_cli.utils import VikingURI
@@ -169,7 +168,7 @@ class SemanticDagExecutor:
semantic_msg_id: Optional[str] = None,
telemetry_id: str = "",
recursive: bool = True,
- lock: LockLease = NO_LOCK,
+ lock: Optional[Dict[str, Any]] = None,
is_code_repo: bool = False,
changes: Optional[Dict[str, List[str]]] = None,
skip_vectorization: bool = False,
@@ -230,15 +229,12 @@ class SemanticDagExecutor:
if self._failure:
raise self._failure
- # Release owned semantic locks after downstream vectorization finishes.
+ # Mark semantic done after downstream vectorization finishes.
async def wrapped_on_complete() -> None:
- try:
- if self._telemetry_id and self._semantic_msg_id:
- get_request_wait_tracker().mark_semantic_done(
- self._telemetry_id, self._semantic_msg_id
- )
- finally:
- await self._lock.close()
+ if self._telemetry_id and self._semantic_msg_id:
+ get_request_wait_tracker().mark_semantic_done(
+ self._telemetry_id, self._semantic_msg_id
+ )
async with self._vectorize_lock:
task_count = self._vectorize_task_count
@@ -264,10 +260,6 @@ class SemanticDagExecutor:
logger.error(f"Error in on_complete callback: {e}", exc_info=True)
except BaseException:
self._closed = True
- try:
- await self._lock.close()
- except Exception:
- pass
raise
finally:
self._closed = True
diff --git a/openviking/storage/queuefs/semantic_lock.py b/openviking/storage/queuefs/semantic_lock.py
index f6e059920..cd82e96d2 100644
--- a/openviking/storage/queuefs/semantic_lock.py
+++ b/openviking/storage/queuefs/semantic_lock.py
@@ -5,25 +5,20 @@
from __future__ import annotations
from dataclasses import dataclass
-from typing import Callable, Iterable, Optional
+from typing import Any, Callable, Dict, Iterable, Optional
from openviking.storage.errors import LockAcquisitionError
-from openviking.storage.transaction import (
- NO_LOCK,
- LockHandoffRef,
- LockLease,
- OwnedLockLease,
- get_lock_manager,
-)
-from openviking.storage.transaction.path_lock import LOCK_FILE_NAME
+from openviking.storage.internal_names import MULTIWRITE_PATH_LOCK_FILE
+from openviking.storage.viking_fs import get_viking_fs
from openviking_cli.utils.logger import get_logger
logger = get_logger(__name__)
-_TREE_LOCK_SUFFIX = f"/{LOCK_FILE_NAME}"
+_TREE_LOCK_SUFFIX = f"/{MULTIWRITE_PATH_LOCK_FILE}"
def _tree_paths_from_handoff(lock_paths: Iterable[str]) -> list[str]:
+ """Extract tree lock directory paths from lock file paths."""
tree_paths: list[str] = []
for lock_path in lock_paths:
if not lock_path.endswith(_TREE_LOCK_SUFFIX):
@@ -38,52 +33,48 @@ def _tree_paths_from_handoff(lock_paths: Iterable[str]) -> list[str]:
class SemanticLockScope:
"""Resolved lock scope for one semantic message."""
- lock: LockLease
+ lock: Optional[Dict[str, Any]] # lease dict or None
+ _owned: bool = False # True when this scope owns the lease (must release)
@classmethod
async def resolve(
cls,
- lock_handoff: Optional[LockHandoffRef],
+ lock_handoff: Optional[Dict[str, Any]],
*,
- caller_lock: LockLease = NO_LOCK,
+ caller_lock: Optional[Dict[str, Any]] = None,
fallback_path_factory: Optional[Callable[[], str]] = None,
) -> "SemanticLockScope":
"""Resolve a live lock, lazily deriving a path for stale legacy handoffs."""
- if lock_handoff and caller_lock.active:
+ if lock_handoff and caller_lock is not None:
raise ValueError("semantic lock must come from either message or caller, not both")
- if caller_lock is not NO_LOCK and not caller_lock.active:
- raise ValueError("caller semantic lock is inactive")
- if caller_lock.active:
- return cls(caller_lock.as_borrowed())
+ if caller_lock is not None:
+ viking_fs = get_viking_fs()
+ return cls(await viking_fs._async_agfs.pathlock_as_borrowed(caller_lock), _owned=False)
if lock_handoff:
- manager = get_lock_manager()
+ viking_fs = get_viking_fs()
try:
- return cls(await OwnedLockLease.from_handoff(lock_handoff, manager=manager))
- except LockAcquisitionError as exc:
- tree_paths = _tree_paths_from_handoff(lock_handoff.lock_paths)
+ return cls(await viking_fs._async_agfs.pathlock_adopt(lock_handoff), _owned=True)
+ except LockAcquisitionError:
+ tree_paths = _tree_paths_from_handoff(lock_handoff["lock_paths"])
if not tree_paths and fallback_path_factory:
tree_paths = [fallback_path_factory()]
if not tree_paths:
raise
- handle = manager.create_handle()
if len(tree_paths) == 1:
- acquired = await manager.acquire_tree(handle, tree_paths[0])
+ lease = await viking_fs._async_agfs.pathlock_acquire_tree(tree_paths[0])
else:
- acquired = await manager.acquire_tree_batch(handle, tree_paths)
- if not acquired:
- await manager.release(handle)
- raise LockAcquisitionError(
- f"Failed to reacquire semantic lock for {tree_paths}"
- ) from exc
+ lease = await viking_fs._async_agfs.pathlock_acquire_tree_batch(tree_paths)
logger.info(
"Recovered semantic lock handoff %s by reacquiring %s",
- lock_handoff.handle_id,
+ lock_handoff.get("owner_id"),
tree_paths,
)
- return cls(OwnedLockLease.from_handle(manager, handle))
- return cls(NO_LOCK)
+ return cls(lease, _owned=True)
+ return cls(None)
async def close(self) -> None:
- await self.lock.close()
+ """Release the owned lock lease if held."""
+ if self.lock is not None and self._owned:
+ await get_viking_fs()._async_agfs.pathlock_release(self.lock)
diff --git a/openviking/storage/queuefs/semantic_msg.py b/openviking/storage/queuefs/semantic_msg.py
index 77ba29add..331288a31 100644
--- a/openviking/storage/queuefs/semantic_msg.py
+++ b/openviking/storage/queuefs/semantic_msg.py
@@ -9,8 +9,6 @@ from typing import Any, Dict, List, Optional
from uuid import uuid4
from openviking.utils.ingest_options import IngestOptions
-from openviking.storage.transaction import LockHandoffRef
-
def build_semantic_coalesce_key(
*,
@@ -53,7 +51,7 @@ class SemanticMsg:
skip_vectorization: bool = False
telemetry_id: str = ""
target_uri: str = ""
- lock_handoff: Optional[LockHandoffRef] = None
+ lock_handoff: Optional[Dict[str, Any]] = None
is_code_repo: bool = False
target_preexisting: Optional[bool] = None
ingest_options: IngestOptions = field(default_factory=IngestOptions)
@@ -75,7 +73,7 @@ class SemanticMsg:
skip_vectorization: bool = False,
telemetry_id: str = "",
target_uri: str = "",
- lock_handoff: Optional[LockHandoffRef] = None,
+ lock_handoff: Optional[Dict[str, Any]] = None,
is_code_repo: bool = False,
target_preexisting: Optional[bool] = None,
ingest_options: IngestOptions | Dict[str, Any] | None = None,
@@ -140,7 +138,7 @@ class SemanticMsg:
skip_vectorization=data.get("skip_vectorization", False),
telemetry_id=data.get("telemetry_id", ""),
target_uri=data.get("target_uri", ""),
- lock_handoff=LockHandoffRef.from_value(data.get("lock_handoff")),
+ lock_handoff=data.get("lock_handoff"),
is_code_repo=data.get("is_code_repo", False),
target_preexisting=data.get("target_preexisting"),
ingest_options=(
diff --git a/openviking/storage/queuefs/semantic_processor.py b/openviking/storage/queuefs/semantic_processor.py
index 3a1b82556..e453e8858 100644
--- a/openviking/storage/queuefs/semantic_processor.py
+++ b/openviking/storage/queuefs/semantic_processor.py
@@ -40,7 +40,6 @@ from openviking.storage.queuefs.semantic_lock import SemanticLockScope
from openviking.storage.queuefs.semantic_msg import SemanticMsg, build_semantic_coalesce_key
from openviking.storage.queuefs.semantic_queue import is_semantic_msg_stale
from openviking.storage.queuefs.semantic_sidecar import write_semantic_sidecars
-from openviking.storage.transaction import NO_LOCK, LockLease
from openviking.storage.viking_fs import LS_ALL_NODES, get_viking_fs
from openviking.telemetry import bind_telemetry, bind_telemetry_stage, resolve_telemetry
from openviking.telemetry.request_wait_tracker import get_request_wait_tracker
@@ -307,7 +306,7 @@ class SemanticProcessor(DequeueHandlerBase):
async def on_dequeue(
self,
data: Optional[Dict[str, Any]],
- lock: LockLease = NO_LOCK,
+ lock: Optional[Dict[str, Any]] = None,
) -> Optional[Dict[str, Any]]:
"""Process dequeued SemanticMsg, recursively process all subdirectories."""
msg: Optional[SemanticMsg] = None
@@ -373,10 +372,8 @@ class SemanticProcessor(DequeueHandlerBase):
msg.uri, ctx=current_ctx
),
)
- lock_transferred = False
try:
if msg.context_type == "memory":
- lock_transferred = True
await self._process_memory_directory(
msg,
ctx=current_ctx,
@@ -445,7 +442,6 @@ class SemanticProcessor(DequeueHandlerBase):
coalesce_key=msg.coalesce_key,
coalesce_version=msg.coalesce_version,
)
- lock_transferred = True
await executor.run(run_uri)
self._cache_dag_stats(
msg.telemetry_id,
@@ -455,8 +451,7 @@ class SemanticProcessor(DequeueHandlerBase):
if not executor.stale:
await self._enqueue_parent_refresh(msg, target_uri or msg.uri)
finally:
- if not lock_transferred:
- await semantic_lock.close()
+ await semantic_lock.close()
self._merge_request_stats(msg.telemetry_id, processed=1)
logger.info(f"Completed semantic generation for: {msg.uri}")
self.report_success()
@@ -523,7 +518,7 @@ class SemanticProcessor(DequeueHandlerBase):
self,
msg: SemanticMsg,
ctx: Optional[RequestContext] = None,
- lock: LockLease = NO_LOCK,
+ lock: Optional[Dict[str, Any]] = None,
) -> None:
"""Process a memory directory with special handling.
@@ -717,7 +712,7 @@ class SemanticProcessor(DequeueHandlerBase):
)
logger.info(f"Vectorized abstract.md and overview.md for {dir_uri}")
finally:
- await lock.close()
+ pass
async def _write_memory_directory_semantics(
self,
@@ -728,7 +723,7 @@ class SemanticProcessor(DequeueHandlerBase):
overview: str,
abstract: str,
ctx: Optional[RequestContext],
- lock: LockLease = NO_LOCK,
+ lock: Optional[Dict[str, Any]] = None,
) -> bool:
return await write_semantic_sidecars(
viking_fs=viking_fs,
@@ -747,7 +742,7 @@ class SemanticProcessor(DequeueHandlerBase):
target_uri: str,
ctx: Optional[RequestContext] = None,
file_change_status: Optional[Dict[str, bool]] = None,
- lock: LockLease = NO_LOCK,
+ lock: Optional[Dict[str, Any]] = None,
) -> DiffResult:
viking_fs = get_viking_fs()
if not await viking_fs.exists(root_uri, ctx=ctx):
@@ -755,7 +750,6 @@ class SemanticProcessor(DequeueHandlerBase):
f"Semantic source no longer exists; refusing to sync into {target_uri}: {root_uri}"
)
diff = DiffResult()
- lock_handle = lock.handle
async def list_children(dir_uri: str) -> Tuple[Dict[str, str], Dict[str, str]]:
files: Dict[str, str] = {}
@@ -793,7 +787,7 @@ class SemanticProcessor(DequeueHandlerBase):
target_conflict_dir,
recursive=True,
ctx=ctx,
- lock_handle=lock_handle,
+ lease_ref=lock,
)
diff.deleted_dirs.append(target_conflict_dir)
target_dirs.pop(name, None)
@@ -805,7 +799,7 @@ class SemanticProcessor(DequeueHandlerBase):
if target_file and name in root_dirs and not root_file:
try:
- await viking_fs.rm(target_file, ctx=ctx, lock_handle=lock_handle)
+ await viking_fs.rm(target_file, ctx=ctx, lease_ref=lock)
diff.deleted_files.append(target_file)
target_files.pop(name, None)
except Exception as e:
@@ -816,7 +810,7 @@ class SemanticProcessor(DequeueHandlerBase):
if target_file and not root_file:
try:
- await viking_fs.rm(target_file, ctx=ctx, lock_handle=lock_handle)
+ await viking_fs.rm(target_file, ctx=ctx, lease_ref=lock)
diff.deleted_files.append(target_file)
except Exception as e:
logger.error(f"[SyncDiff] Failed to delete file: {target_file}, error={e}")
@@ -839,7 +833,7 @@ class SemanticProcessor(DequeueHandlerBase):
if changed:
diff.updated_files.append(target_file)
try:
- await viking_fs.rm(target_file, ctx=ctx, lock_handle=lock_handle)
+ await viking_fs.rm(target_file, ctx=ctx, lease_ref=lock)
except Exception as e:
logger.error(
f"[SyncDiff] Failed to remove old file before update: {target_file}, error={e}"
@@ -849,7 +843,7 @@ class SemanticProcessor(DequeueHandlerBase):
root_file,
target_file,
ctx=ctx,
- lock_handle=lock_handle,
+ lease_ref=lock,
)
except Exception as e:
logger.error(
@@ -865,7 +859,7 @@ class SemanticProcessor(DequeueHandlerBase):
root_file,
target_file_uri,
ctx=ctx,
- lock_handle=lock_handle,
+ lease_ref=lock,
)
except Exception as e:
logger.error(
@@ -883,7 +877,7 @@ class SemanticProcessor(DequeueHandlerBase):
await viking_fs.rm(
target_conflict_file,
ctx=ctx,
- lock_handle=lock_handle,
+ lease_ref=lock,
)
diff.deleted_files.append(target_conflict_file)
target_files.pop(name, None)
@@ -899,7 +893,7 @@ class SemanticProcessor(DequeueHandlerBase):
target_subdir,
recursive=True,
ctx=ctx,
- lock_handle=lock_handle,
+ lease_ref=lock,
)
diff.deleted_dirs.append(target_subdir)
except Exception as e:
@@ -916,7 +910,7 @@ class SemanticProcessor(DequeueHandlerBase):
root_subdir,
target_subdir_uri,
ctx=ctx,
- lock_handle=lock_handle,
+ lease_ref=lock,
)
except Exception as e:
logger.error(
@@ -931,9 +925,14 @@ class SemanticProcessor(DequeueHandlerBase):
if not target_exists:
parent_uri = VikingURI(target_uri).parent
if parent_uri:
- await viking_fs.mkdir(parent_uri.uri, exist_ok=True, ctx=ctx)
+ await viking_fs.mkdir(
+ parent_uri.uri,
+ exist_ok=True,
+ ctx=ctx,
+ lease_ref=lock,
+ )
diff.added_dirs.append(target_uri)
- await viking_fs.mv(root_uri, target_uri, ctx=ctx, lock_handle=lock_handle)
+ await viking_fs.mv(root_uri, target_uri, ctx=ctx, lease_ref=lock)
# The whole temp tree (including the hidden .image_mappings.json
# sidecar) was moved into the target; rewrite local image paths now.
await self._rewrite_target_image_uris(root_uri, target_uri, ctx=ctx, lock=lock)
@@ -955,7 +954,7 @@ class SemanticProcessor(DequeueHandlerBase):
root_uri: str,
target_uri: str,
ctx: Optional[RequestContext] = None,
- lock: LockLease = NO_LOCK,
+ lock: Optional[Dict[str, Any]] = None,
) -> None:
"""Rewrite local image refs in the target after a temp-to-target sync.
@@ -1018,14 +1017,14 @@ class SemanticProcessor(DequeueHandlerBase):
target_mapping,
mapping_content,
ctx=ctx,
- lock_handle=lock.handle,
+ lease_ref=lock,
)
except Exception:
# Target subtree may not exist (doc removed in sync); skip.
pass
try:
- await rewrite_image_uris(target_uri, ctx=ctx, lock_handle=lock.handle)
+ await rewrite_image_uris(target_uri, ctx=ctx, lease_ref=lock)
except Exception as e:
logger.error(f"[SyncDiff] Failed to rewrite image URIs for {target_uri}: {e}")
diff --git a/openviking/storage/queuefs/semantic_sidecar.py b/openviking/storage/queuefs/semantic_sidecar.py
index 0c5c083fd..093001491 100644
--- a/openviking/storage/queuefs/semantic_sidecar.py
+++ b/openviking/storage/queuefs/semantic_sidecar.py
@@ -2,10 +2,9 @@
# SPDX-License-Identifier: AGPL-3.0
"""Shared writeback for semantic sidecar files."""
-from typing import Any, Callable, Optional
+from typing import Any, Callable, Dict, Optional
from openviking.server.identity import RequestContext
-from openviking.storage.transaction import NO_LOCK, LockLease
from openviking_cli.utils.logger import get_logger
logger = get_logger(__name__)
@@ -19,34 +18,31 @@ async def write_semantic_sidecars(
abstract: str,
ctx: Optional[RequestContext],
is_stale: Callable[[], bool],
- lock: LockLease = NO_LOCK,
+ lock: Optional[Dict[str, Any]] = None,
log_prefix: str = "[Semantic]",
) -> bool:
+ """Write .overview.md and .abstract.md sidecar files under dir_uri with exact-path locking."""
if is_stale():
logger.info("%s Skipping stale semantic write for %s", log_prefix, dir_uri)
return False
- try:
- from openviking.storage.transaction import (
- LockContext,
- get_lock_manager,
- )
-
- lock_manager = get_lock_manager()
- except Exception:
- await _write_sidecars(viking_fs, dir_uri, overview, abstract, ctx, lock.handle)
- return True
-
lock_paths = [
viking_fs._uri_to_path(f"{dir_uri}/.overview.md", ctx=ctx),
viking_fs._uri_to_path(f"{dir_uri}/.abstract.md", ctx=ctx),
]
- async with LockContext(lock_manager, lock_paths, lock_mode="exact", handle=lock.handle):
+ sidecar_lease = lock
+ owns_lease = sidecar_lease is None
+ if sidecar_lease is None:
+ sidecar_lease = await viking_fs._async_agfs.pathlock_acquire_exact_batch(lock_paths)
+ try:
if is_stale():
logger.info("%s Skipping stale semantic write for %s", log_prefix, dir_uri)
return False
- await _write_sidecars(viking_fs, dir_uri, overview, abstract, ctx, lock.handle)
+ await _write_sidecars(viking_fs, dir_uri, overview, abstract, ctx, sidecar_lease)
return True
+ finally:
+ if owns_lease:
+ await viking_fs._async_agfs.pathlock_release(sidecar_lease)
async def _write_sidecars(
@@ -55,18 +51,18 @@ async def _write_sidecars(
overview: str,
abstract: str,
ctx: Optional[RequestContext],
- lock_handle: Any = None,
+ lease_ref: Optional[Dict[str, Any]] = None,
) -> None:
- # TODO: This must be optimized once pathlock is pushed down into ragfs.
+ """Write sidecar files to the target directory."""
await viking_fs.write_file(
f"{dir_uri}/.overview.md",
overview,
ctx=ctx,
- lock_handle=lock_handle,
+ lease_ref=lease_ref,
)
await viking_fs.write_file(
f"{dir_uri}/.abstract.md",
abstract,
ctx=ctx,
- lock_handle=lock_handle,
+ lease_ref=lease_ref,
)
diff --git a/openviking/storage/transaction/__init__.py b/openviking/storage/transaction/__init__.py
index cdcd30756..93e772ac0 100644
--- a/openviking/storage/transaction/__init__.py
+++ b/openviking/storage/transaction/__init__.py
@@ -3,46 +3,12 @@
"""
Transaction module for OpenViking.
-Provides path-lock management and redo-log crash recovery.
+Path-lock management has been moved to the Rust ragfs layer.
+Python-side lock operations now go through RAGFSBindingClient.pathlock_* methods.
"""
-from openviking.storage.transaction.lock_context import LockContext
-from openviking.storage.transaction.lock_handle import LockHandle, LockOwner
-from openviking.storage.transaction.lock_lease import (
- NO_LOCK,
- BorrowedLockLease,
- LockHandoffRef,
- LockLease,
- OwnedLockLease,
-)
-from openviking.storage.transaction.lock_manager import (
- LOCK_TIMEOUT_DEFAULT,
- LockManager,
- get_lock_handle_async,
- get_lock_manager,
- init_lock_manager,
- release_all_locks,
- reset_lock_manager,
-)
-from openviking.storage.transaction.path_lock import PathLockEngine
from openviking.storage.transaction.redo_log import RedoLog
__all__ = [
- "BorrowedLockLease",
- "LockContext",
- "LockHandle",
- "LockHandoffRef",
- "LockLease",
- "LOCK_TIMEOUT_DEFAULT",
- "LockManager",
- "LockOwner",
- "NO_LOCK",
- "OwnedLockLease",
- "PathLockEngine",
"RedoLog",
- "get_lock_handle_async",
- "get_lock_manager",
- "init_lock_manager",
- "release_all_locks",
- "reset_lock_manager",
]
diff --git a/openviking/storage/transaction/lock_context.py b/openviking/storage/transaction/lock_context.py
deleted file mode 100644
index 424cca343..000000000
--- a/openviking/storage/transaction/lock_context.py
+++ /dev/null
@@ -1,97 +0,0 @@
-# Copyright (c) 2026 Beijing Volcano Engine Technology Co., Ltd.
-# SPDX-License-Identifier: AGPL-3.0
-"""LockContext — async context manager for acquiring/releasing path locks."""
-
-from typing import Any, Optional
-
-from openviking.storage.errors import LockAcquisitionError
-from openviking.storage.transaction.lock_handle import LockHandle
-from openviking.storage.transaction.lock_lease import OwnedLockLease
-from openviking.storage.transaction.lock_manager import LOCK_TIMEOUT_DEFAULT, LockManager
-
-
-class LockContext:
- """``async with LockContext(manager, paths, mode) as handle: ...``
-
- Acquires locks on entry, releases them on exit. No undo / journal / commit
- semantics — just a lock scope.
- """
-
- def __init__(
- self,
- lock_manager: LockManager,
- paths: list[str],
- lock_mode: str = "exact",
- mv_dst_path: Optional[str] = None,
- src_is_dir: bool = True,
- handle: Optional[LockHandle] = None,
- timeout: Any = LOCK_TIMEOUT_DEFAULT,
- ):
- self._manager = lock_manager
- self._paths = paths
- self._lock_mode = lock_mode
- self._mv_dst_path = mv_dst_path
- self._src_is_dir = src_is_dir
- self._handle: Optional[LockHandle] = handle
- self._timeout = timeout
- self._owns_handle = handle is None
- self._locks_before: list[str] = []
- self._acquired_lock_paths: list[str] = []
- self._owned_lease: Optional[OwnedLockLease] = None
-
- async def __aenter__(self) -> LockHandle:
- if self._handle is None:
- self._handle = self._manager.create_handle()
- self._locks_before = list(self._handle.locks)
- success = False
-
- if self._lock_mode == "tree":
- for path in self._paths:
- success = await self._manager.acquire_tree(
- self._handle, path, timeout=self._timeout
- )
- if not success:
- break
- elif self._lock_mode == "exact":
- success = await self._manager.acquire_exact_path_batch(
- self._handle, self._paths, timeout=self._timeout
- )
- elif self._lock_mode == "mv":
- if self._mv_dst_path is None:
- raise LockAcquisitionError("mv lock mode requires mv_dst_path")
- success = await self._manager.acquire_mv(
- self._handle,
- self._paths[0],
- self._mv_dst_path,
- src_is_dir=self._src_is_dir,
- timeout=self._timeout,
- )
- else:
- raise LockAcquisitionError(f"Unsupported lock mode: {self._lock_mode}")
-
- self._acquired_lock_paths = [
- lock_path for lock_path in self._handle.locks if lock_path not in self._locks_before
- ]
-
- if not success:
- if self._owns_handle:
- await self._manager.release(self._handle)
- else:
- await self._manager.release_selected(self._handle, self._acquired_lock_paths)
- raise LockAcquisitionError(
- f"Failed to acquire {self._lock_mode} lock for {self._paths}"
- )
- if self._owns_handle and self._handle.locks:
- self._owned_lease = OwnedLockLease.from_handle(self._manager, self._handle)
- return self._handle
-
- async def __aexit__(self, exc_type, exc_val, exc_tb):
- if self._handle:
- if self._owns_handle:
- if self._owned_lease:
- await self._owned_lease.close()
- else:
- await self._manager.release(self._handle)
- else:
- await self._manager.release_selected(self._handle, self._acquired_lock_paths)
- return False
diff --git a/openviking/storage/transaction/lock_handle.py b/openviking/storage/transaction/lock_handle.py
deleted file mode 100644
index 0e2c8f084..000000000
--- a/openviking/storage/transaction/lock_handle.py
+++ /dev/null
@@ -1,48 +0,0 @@
-# Copyright (c) 2026 Beijing Volcano Engine Technology Co., Ltd.
-# SPDX-License-Identifier: AGPL-3.0
-"""Lock handle and LockOwner protocol for path lock integration."""
-
-import time
-import uuid
-from dataclasses import dataclass, field
-from typing import Protocol, runtime_checkable
-
-
-def _new_lock_id() -> str:
- return str(uuid.uuid4())
-
-
-@runtime_checkable
-class LockOwner(Protocol):
- """Minimal interface that path lock code requires from its caller."""
-
- id: str
- locks: list[str]
-
- def add_lock(self, path: str) -> None:
- raise NotImplementedError
-
- def remove_lock(self, path: str) -> None:
- raise NotImplementedError
-
-
-@dataclass
-class LockHandle:
- """Identifies a lock holder. Path lock code uses ``id`` to generate fencing tokens
- and ``locks`` to track acquired lock files."""
-
- id: str = field(default_factory=_new_lock_id)
- locks: list[str] = field(default_factory=list)
- created_at: float = field(default_factory=time.time)
- last_active_at: float = field(init=False)
-
- def __post_init__(self) -> None:
- self.last_active_at = self.created_at
-
- def add_lock(self, lock_path: str) -> None:
- if lock_path not in self.locks:
- self.locks.append(lock_path)
-
- def remove_lock(self, lock_path: str) -> None:
- if lock_path in self.locks:
- self.locks.remove(lock_path)
diff --git a/openviking/storage/transaction/lock_lease.py b/openviking/storage/transaction/lock_lease.py
deleted file mode 100644
index 3cbf26ddb..000000000
--- a/openviking/storage/transaction/lock_lease.py
+++ /dev/null
@@ -1,229 +0,0 @@
-# Copyright (c) 2026 Beijing Volcano Engine Technology Co., Ltd.
-# SPDX-License-Identifier: AGPL-3.0
-"""Typed lock ownership helpers for path-lock users."""
-
-from __future__ import annotations
-
-import asyncio
-from contextlib import suppress
-from dataclasses import dataclass
-from typing import Any, Iterable, Optional
-
-from openviking.storage.errors import LockAcquisitionError
-from openviking.storage.transaction.lock_handle import LockHandle
-from openviking.storage.transaction.lock_manager import (
- LOCK_TIMEOUT_DEFAULT,
- LockManager,
- get_lock_manager,
-)
-from openviking_cli.utils.logger import get_logger
-
-logger = get_logger(__name__)
-
-
-@dataclass(frozen=True)
-class LockHandoffRef:
- """Serializable reference used to hand lock ownership through a queue."""
-
- handle_id: str
- lock_paths: tuple[str, ...] = ()
-
- @classmethod
- def from_value(cls, value: Any) -> Optional["LockHandoffRef"]:
- if value is None:
- return None
- if isinstance(value, LockHandoffRef):
- return value
- if not isinstance(value, dict):
- raise ValueError("lock_handoff must be an object")
-
- handle_id = value.get("handle_id")
- if not handle_id:
- return None
- lock_paths = tuple(str(path) for path in value.get("lock_paths", []) if path)
- return cls(handle_id=str(handle_id), lock_paths=lock_paths)
-
- def to_dict(self) -> dict[str, Any]:
- return {"handle_id": self.handle_id, "lock_paths": list(self.lock_paths)}
-
-
-class LockLease:
- """Base lock lease interface."""
-
- @property
- def handle(self) -> Optional[LockHandle]:
- return None
-
- @property
- def handle_id(self) -> str:
- handle = self.handle
- return handle.id if handle else ""
-
- @property
- def active(self) -> bool:
- handle = self.handle
- return bool(handle and handle.locks)
-
- def as_borrowed(self) -> "LockLease":
- return self
-
- def to_handoff(self) -> Optional[LockHandoffRef]:
- return None
-
- async def close(self) -> None:
- return
-
- async def handoff(self) -> None:
- return
-
-
-class _NoLockLease(LockLease):
- pass
-
-
-NO_LOCK: LockLease = _NoLockLease()
-
-
-@dataclass
-class BorrowedLockLease(LockLease):
- """A lock lease borrowed from an outer owner."""
-
- manager: LockManager
- _handle: LockHandle
-
- @classmethod
- def from_handle(cls, manager: LockManager, handle: LockHandle) -> "BorrowedLockLease":
- return cls(manager=manager, _handle=handle)
-
- @property
- def handle(self) -> Optional[LockHandle]:
- return self.manager.get_handle(self._handle.id)
-
- def as_borrowed(self) -> "LockLease":
- return self
-
-
-class OwnedLockLease(LockLease):
- """An owned lock lease that refreshes and releases its handle."""
-
- def __init__(
- self,
- manager: LockManager,
- handle: LockHandle,
- *,
- start_refresh: bool = True,
- ):
- self._manager = manager
- self._handle: Optional[LockHandle] = handle
- self._refresh_task: Optional[asyncio.Task] = None
- if start_refresh and handle.locks:
- self._start_refresh()
-
- @classmethod
- def from_handle(cls, manager: LockManager, handle: LockHandle) -> "OwnedLockLease":
- return cls(manager, handle)
-
- @classmethod
- async def from_handoff(
- cls,
- ref: LockHandoffRef,
- manager: Optional[LockManager] = None,
- ) -> "OwnedLockLease":
- manager = manager or get_lock_manager()
- handle = await manager.get_handle_async(ref.handle_id)
- if handle is None:
- handle = await manager.adopt_handle_async(ref.handle_id, ref.lock_paths)
- if handle is None:
- raise LockAcquisitionError(f"Lock handle is no longer active: {ref.handle_id}")
- return cls(manager, handle)
-
- @classmethod
- async def acquire_tree(
- cls,
- manager: LockManager,
- path: str,
- *,
- timeout: Any = LOCK_TIMEOUT_DEFAULT,
- ) -> "OwnedLockLease":
- handle = manager.create_handle()
- if await manager.acquire_tree(handle, path, timeout=timeout):
- return cls(manager, handle)
- await manager.release(handle)
- raise LockAcquisitionError(f"Failed to acquire tree lock for {path}")
-
- @classmethod
- async def acquire_exact_paths(
- cls,
- manager: LockManager,
- paths: Iterable[str],
- *,
- timeout: Any = LOCK_TIMEOUT_DEFAULT,
- ) -> "OwnedLockLease":
- handle = manager.create_handle()
- path_list = list(paths)
- if await manager.acquire_exact_path_batch(handle, path_list, timeout=timeout):
- return cls(manager, handle)
- await manager.release(handle)
- raise LockAcquisitionError(f"Failed to acquire exact lock for {path_list}")
-
- @property
- def handle(self) -> Optional[LockHandle]:
- if self._handle is None:
- return None
- return self._manager.get_handle(self._handle.id)
-
- def as_borrowed(self) -> LockLease:
- handle = self.handle
- if handle is None:
- return NO_LOCK
- return BorrowedLockLease.from_handle(self._manager, handle)
-
- def to_handoff(self) -> Optional[LockHandoffRef]:
- handle = self.handle
- if handle is None:
- return None
- return LockHandoffRef(handle_id=handle.id, lock_paths=tuple(handle.locks))
-
- async def close(self) -> None:
- await self._stop_refresh()
- handle = self.handle or self._handle
- self._handle = None
- if handle is not None:
- await self._manager.release(handle)
-
- async def handoff(self) -> None:
- """Stop managing this lease after another worker has received its handle."""
- await self._stop_refresh()
- self._handle = None
-
- def _start_refresh(self) -> None:
- if self._refresh_task is not None:
- return
- self._refresh_task = asyncio.create_task(self._refresh_loop())
-
- async def _refresh_loop(self) -> None:
- try:
- expire = self._manager._path_lock._lock_expire
- interval = max(0.1, expire / 2)
- except Exception:
- interval = 150.0
-
- while True:
- try:
- await asyncio.sleep(interval)
- handle = self.handle
- if handle is None:
- return
- await self._manager.refresh_lock(handle)
- except asyncio.CancelledError:
- raise
- except Exception as exc:
- logger.warning("Failed to refresh lock handle %s: %s", self.handle_id, exc)
-
- async def _stop_refresh(self) -> None:
- if self._refresh_task is None:
- return
- self._refresh_task.cancel()
- with suppress(asyncio.CancelledError):
- await self._refresh_task
- self._refresh_task = None
diff --git a/openviking/storage/transaction/lock_manager.py b/openviking/storage/transaction/lock_manager.py
deleted file mode 100644
index d31efc612..000000000
--- a/openviking/storage/transaction/lock_manager.py
+++ /dev/null
@@ -1,594 +0,0 @@
-# Copyright (c) 2026 Beijing Volcano Engine Technology Co., Ltd.
-# SPDX-License-Identifier: AGPL-3.0
-"""LockManager — global singleton managing lock lifecycle and redo recovery."""
-
-import asyncio
-import json
-import time
-from typing import Any, Dict, List, Optional, Protocol
-
-from openviking.pyagfs import AGFSSyncClientProtocol, AsyncAGFSClient
-from openviking.storage.transaction.lock_handle import LockHandle
-from openviking.storage.transaction.path_lock import PathLockEngine
-from openviking.storage.transaction.redo_log import RedoLog
-from openviking_cli.utils.logger import get_logger
-
-logger = get_logger(__name__)
-
-_HANDLE_CLEANUP_INTERVAL_SECONDS = 60.0
-LOCK_TIMEOUT_DEFAULT = object()
-
-
-class _LockManagerLike(Protocol):
- def get_handle(self, handle_id: str) -> Optional[LockHandle]: ...
-
-
-async def get_lock_handle_async(
- lock_manager: _LockManagerLike, handle_id: str
-) -> Optional[LockHandle]:
- getter = getattr(lock_manager, "get_handle_async", None)
- if getter is not None:
- return await getter(handle_id)
- return await asyncio.to_thread(lock_manager.get_handle, handle_id)
-
-
-class LockManager:
- """Global singleton. Manages lock lifecycle and stale cleanup."""
-
- def __init__(
- self,
- agfs: AGFSSyncClientProtocol,
- lock_timeout: float = 0.0,
- lock_expire: float = 300.0,
- redo_recovery_enabled: bool = True,
- ):
- self._agfs = agfs
- self._async_agfs = AsyncAGFSClient(agfs)
- self._path_lock = PathLockEngine(agfs, lock_expire=lock_expire)
- self._lock_timeout = lock_timeout
- self._redo_recovery_enabled = redo_recovery_enabled
- self._redo_log = RedoLog(agfs)
- self._handles: Dict[str, LockHandle] = {}
- self._cleanup_task: Optional[asyncio.Task] = None
- self._redo_task: Optional[asyncio.Task] = None
- self._running = False
-
- @property
- def redo_recovery_enabled(self) -> bool:
- return self._redo_recovery_enabled
-
- def _resolve_timeout(self, timeout: Any) -> Optional[float]:
- return self._lock_timeout if timeout is LOCK_TIMEOUT_DEFAULT else timeout
-
- def _mark_handle_active(self, handle: LockHandle) -> None:
- handle.last_active_at = time.time()
-
- def get_active_handles(self) -> Dict[str, LockHandle]:
- active_handles: Dict[str, LockHandle] = {}
- for handle in list(self._handles.values()):
- current = self._reconcile_handle(handle)
- if current and current.locks:
- active_handles[current.id] = current
- return active_handles
-
- async def get_active_handles_async(self) -> Dict[str, LockHandle]:
- active_handles: Dict[str, LockHandle] = {}
- for handle in list(self._handles.values()):
- current = await self._reconcile_handle_async(handle)
- if current and current.locks:
- active_handles[current.id] = current
- return active_handles
-
- async def start(self) -> None:
- """Start background cleanup and redo recovery."""
- self._running = True
- self._cleanup_task = asyncio.create_task(self._stale_cleanup_loop())
- if self._redo_recovery_enabled:
- self._redo_task = asyncio.create_task(self._recover_pending_redo())
- else:
- logger.info("Redo recovery disabled by config; skipping pending redo recovery")
-
- async def stop(self) -> None:
- """Stop cleanup and release all active locks."""
- self._running = False
- if self._redo_task:
- self._redo_task.cancel()
- try:
- await self._redo_task
- except asyncio.CancelledError:
- pass
- self._redo_task = None
- if self._cleanup_task:
- self._cleanup_task.cancel()
- try:
- if self._cleanup_task.get_loop() is asyncio.get_running_loop():
- await self._cleanup_task
- except asyncio.CancelledError:
- pass
- self._cleanup_task = None
- for handle in list(self._handles.values()):
- await self._path_lock.release(handle)
- self._handles.clear()
-
- def create_handle(self) -> LockHandle:
- handle = LockHandle()
- self._handles[handle.id] = handle
- return handle
-
- async def acquire_exact_path(
- self,
- handle: LockHandle,
- path: str,
- timeout: Any = LOCK_TIMEOUT_DEFAULT,
- ) -> bool:
- acquired = await self._path_lock.acquire_exact_path(
- path, handle, timeout=self._resolve_timeout(timeout)
- )
- if acquired:
- self._mark_handle_active(handle)
- return acquired
-
- async def acquire_tree(
- self,
- handle: LockHandle,
- path: str,
- timeout: Any = LOCK_TIMEOUT_DEFAULT,
- ) -> bool:
- acquired = await self._path_lock.acquire_tree(
- path, handle, timeout=self._resolve_timeout(timeout)
- )
- if acquired:
- self._mark_handle_active(handle)
- return acquired
-
- async def acquire_tree_batch(
- self,
- handle: LockHandle,
- paths: List[str],
- timeout: Any = LOCK_TIMEOUT_DEFAULT,
- ) -> bool:
- """
- 一次性对多个路径进行树锁加锁,使用有序加锁法防止死锁
-
- 核心思想:
- 1. 对路径按照固定的顺序进行排序,确保所有进程获取锁的顺序一致
- 2. 防止循环等待条件,从而避免死锁
-
- 排序规则:
- 1. 路径长度升序
- 2. 长度相同的路径按照字典序升序
-
- Args:
- handle: 锁句柄
- paths: 需要加锁的路径列表
- timeout: 超时时间,None表示无限等待
-
- Returns:
- 是否成功获取所有锁
- """
- if not paths:
- self._mark_handle_active(handle)
- return True
-
- sorted_paths = sorted(paths, key=lambda x: (len(x), x))
- acquired_lock_paths: List[str] = []
-
- try:
- for path in sorted_paths:
- locks_before = set(handle.locks)
- success = await self._path_lock.acquire_tree(
- path,
- handle,
- timeout=self._resolve_timeout(timeout),
- )
- if not success:
- await self._path_lock.release_selected(handle, acquired_lock_paths)
- return False
- newly = [lp for lp in handle.locks if lp not in locks_before]
- acquired_lock_paths.extend(newly)
-
- self._mark_handle_active(handle)
- return True
-
- except Exception as e:
- logger.error(f"Failed to acquire tree batch lock: {e}")
- await self._path_lock.release_selected(handle, acquired_lock_paths)
- return False
-
- async def acquire_exact_path_batch(
- self,
- handle: LockHandle,
- paths: List[str],
- timeout: Any = LOCK_TIMEOUT_DEFAULT,
- ) -> bool:
- if not paths:
- self._mark_handle_active(handle)
- return True
-
- sorted_paths = sorted(dict.fromkeys(paths), key=lambda x: (len(x), x))
- acquired_lock_paths: List[str] = []
-
- try:
- for path in sorted_paths:
- locks_before = set(handle.locks)
- success = await self._path_lock.acquire_exact_path(
- path,
- handle,
- timeout=self._resolve_timeout(timeout),
- )
- if not success:
- await self._path_lock.release_selected(handle, acquired_lock_paths)
- return False
- newly = [lp for lp in handle.locks if lp not in locks_before]
- acquired_lock_paths.extend(newly)
-
- self._mark_handle_active(handle)
- return True
-
- except Exception as e:
- logger.error(f"Failed to acquire exact-path batch lock: {e}")
- await self._path_lock.release_selected(handle, acquired_lock_paths)
- return False
-
- async def acquire_exact_tree_batch(
- self,
- handle: LockHandle,
- exact_paths: List[str],
- tree_paths: List[str],
- timeout: Any = LOCK_TIMEOUT_DEFAULT,
- ) -> bool:
- exact_set = set(exact_paths)
- tree_set = set(tree_paths)
- exact_only = [p for p in exact_set if p not in tree_set]
- all_pairs = [(p, False) for p in exact_only] + [(p, True) for p in tree_set]
-
- if not all_pairs:
- self._mark_handle_active(handle)
- return True
-
- sorted_pairs = sorted(all_pairs, key=lambda x: (len(x[0]), x[0]))
- acquired_lock_paths: List[str] = []
-
- try:
- for path, is_tree in sorted_pairs:
- locks_before = set(handle.locks)
- if is_tree:
- success = await self._path_lock.acquire_tree(
- path,
- handle,
- timeout=self._resolve_timeout(timeout),
- )
- else:
- success = await self._path_lock.acquire_exact_path(
- path,
- handle,
- timeout=self._resolve_timeout(timeout),
- )
- if not success:
- await self._path_lock.release_selected(handle, acquired_lock_paths)
- return False
- newly = [lp for lp in handle.locks if lp not in locks_before]
- acquired_lock_paths.extend(newly)
-
- self._mark_handle_active(handle)
- return True
-
- except Exception as e:
- logger.error(f"Failed to acquire exact/tree batch lock: {e}")
- await self._path_lock.release_selected(handle, acquired_lock_paths)
- return False
-
- async def acquire_mv(
- self,
- handle: LockHandle,
- src: str,
- dst: str,
- src_is_dir: bool = True,
- timeout: Any = LOCK_TIMEOUT_DEFAULT,
- ) -> bool:
- acquired = await self._path_lock.acquire_mv(
- src,
- dst,
- handle,
- timeout=self._resolve_timeout(timeout),
- src_is_dir=src_is_dir,
- )
- if acquired:
- self._mark_handle_active(handle)
- return acquired
-
- def get_handle(self, handle_id: str) -> Optional[LockHandle]:
- handle = self._handles.get(handle_id)
- if handle is None:
- return None
- current = self._reconcile_handle(handle)
- if current is None or not current.locks:
- return None
- return current
-
- def adopt_handle(self, handle_id: str, lock_paths: List[str]) -> Optional[LockHandle]:
- handle = self.get_handle(handle_id)
- if handle is not None:
- return handle
-
- adopted = LockHandle(id=handle_id)
- for lock_path in dict.fromkeys(lock_paths):
- if self._path_lock.is_lock_owned_by(lock_path, handle_id):
- adopted.add_lock(lock_path)
- if not adopted.locks:
- return None
-
- self._handles[adopted.id] = adopted
- self._mark_handle_active(adopted)
- return adopted
-
- async def adopt_handle_async(
- self, handle_id: str, lock_paths: List[str]
- ) -> Optional[LockHandle]:
- handle = await self.get_handle_async(handle_id)
- if handle is not None:
- return handle
-
- adopted = LockHandle(id=handle_id)
- for lock_path in dict.fromkeys(lock_paths):
- if await self._path_lock.is_lock_owned_by_async(lock_path, handle_id):
- adopted.add_lock(lock_path)
- if not adopted.locks:
- return None
-
- self._handles[adopted.id] = adopted
- self._mark_handle_active(adopted)
- return adopted
-
- async def get_handle_async(self, handle_id: str) -> Optional[LockHandle]:
- handle = self._handles.get(handle_id)
- if handle is None:
- return None
- current = await self._reconcile_handle_async(handle)
- if current is None or not current.locks:
- return None
- return current
-
- def is_path_locked(self, path: str, ignore_stale: bool = True) -> bool:
- """Check whether *path* is currently locked.
-
- Semantics align with conflict detection in the acquire flow: the path
- is considered locked if it (or any ancestor) holds a lock. By default,
- stale locks are ignored because they will be reclaimed on the next
- acquire attempt.
- """
- try:
- return self._path_lock.is_locked(path, ignore_stale=ignore_stale)
- except Exception as e:
- logger.warning(f"is_path_locked failed for {path}: {e}")
- return False
-
- async def is_path_locked_async(self, path: str, ignore_stale: bool = True) -> bool:
- """Async variant for request/background paths."""
- try:
- return await self._path_lock.is_locked_async(path, ignore_stale=ignore_stale)
- except Exception as e:
- logger.warning(f"is_path_locked_async failed for {path}: {e}")
- return False
-
- async def refresh_lock(self, handle: LockHandle) -> None:
- current = await self._reconcile_handle_async(handle)
- if current is None:
- return
-
- result = await self._path_lock.refresh(current)
- for lock_path in result.lost_paths:
- current.remove_lock(lock_path)
-
- if result.refreshed_paths:
- self._mark_handle_active(current)
-
- await self._reconcile_handle_async(current)
-
- async def release(self, handle: LockHandle) -> None:
- await self._path_lock.release(handle)
- self._handles.pop(handle.id, None)
-
- async def release_selected(self, handle: LockHandle, lock_paths: List[str]) -> None:
- await self._path_lock.release_selected(handle, lock_paths)
-
- async def _stale_cleanup_loop(self) -> None:
- """Check and release leaked handles every 60 s (in-process safety net)."""
- while self._running:
- await asyncio.sleep(_HANDLE_CLEANUP_INTERVAL_SECONDS)
- now = time.time()
- stale = []
- for handle in list(self._handles.values()):
- current = await self._reconcile_handle_async(handle)
- if current and self._is_handle_stale(current, now):
- stale.append(current)
- for handle in stale:
- logger.warning(f"Releasing stale lock handle {handle.id}")
- await self.release(handle)
-
- def _is_handle_stale(self, handle: LockHandle, now: Optional[float] = None) -> bool:
- """Return True when a live lock handle has stopped refreshing for too long."""
- if not handle.locks:
- return False
- if now is None:
- now = time.time()
- return now - handle.last_active_at > self._path_lock._lock_expire
-
- def _reconcile_handle(self, handle: LockHandle) -> Optional[LockHandle]:
- had_locks = bool(handle.locks)
- lost_paths = self._path_lock.collect_lost_owner_locks(handle)
- for lock_path in lost_paths:
- handle.remove_lock(lock_path)
- if had_locks and not handle.locks:
- self._handles.pop(handle.id, None)
- return None
- return handle
-
- async def _reconcile_handle_async(self, handle: LockHandle) -> Optional[LockHandle]:
- had_locks = bool(handle.locks)
- lost_paths = await self._path_lock.collect_lost_owner_locks_async(handle)
- for lock_path in lost_paths:
- handle.remove_lock(lock_path)
- if had_locks and not handle.locks:
- self._handles.pop(handle.id, None)
- return None
- return handle
-
- # ------------------------------------------------------------------
- # Redo recovery (session_memory only)
- # ------------------------------------------------------------------
-
- async def _recover_pending_redo(self) -> None:
- pending_ids = await self._redo_log.list_pending_async()
- for task_id in pending_ids:
- logger.info(f"Recovering pending redo task: {task_id}")
- try:
- info = await self._redo_log.read_async(task_id)
- if info:
- await self._redo_session_memory(info)
- await self._redo_log.mark_done_async(task_id)
- except Exception as e:
- logger.error(f"Redo recovery failed for {task_id}: {e}", exc_info=True)
-
- async def _redo_session_memory(self, info: Dict[str, Any]) -> None:
- """Re-extract memories from archive.
-
- Lets exceptions from _enqueue_semantic propagate so the caller
- can decide whether to mark the redo task as done.
- """
- from openviking.message import Message
- from openviking.server.identity import RequestContext, Role
- from openviking.storage.viking_fs import get_viking_fs
- from openviking_cli.session.user_id import UserIdentifier
-
- archive_uri = info.get("archive_uri")
- session_uri = info.get("session_uri")
- account_id = info.get("account_id", "default")
- user_id = info.get("user_id", "default")
- role_str = info.get("role", "root")
-
- if not archive_uri or not session_uri:
- raise ValueError("Cannot redo session_memory: missing archive_uri or session_uri")
-
- # 1. Build request context (needed for path conversion below)
- user = UserIdentifier(account_id=account_id, user_id=user_id)
- ctx = RequestContext(user=user, role=Role(role_str))
-
- # 2. Read archived messages
- messages_uri = f"{archive_uri}/messages.jsonl"
- viking_fs = get_viking_fs()
- agfs_path = viking_fs._uri_to_path(messages_uri, ctx=ctx)
- messages = []
- try:
- content = await self._async_agfs.cat(agfs_path)
- if isinstance(content, bytes):
- content = content.decode("utf-8")
- for line in content.strip().split("\n"):
- if line.strip():
- try:
- messages.append(Message.from_dict(json.loads(line)))
- except Exception:
- pass
- except Exception as e:
- logger.warning(f"Cannot read archive for redo: {agfs_path}: {e}")
-
- # 3. Re-extract memories (best-effort, only if archive was readable)
- if messages:
- session_id = session_uri.rstrip("/").rsplit("/", 1)[-1]
- try:
- from openviking.session import create_session_compressor
-
- compressor = create_session_compressor(vikingdb=None)
- memories = await asyncio.wait_for(
- compressor.extract_long_term_memories(
- messages=messages,
- user=user,
- session_id=session_id,
- ctx=ctx,
- ),
- timeout=60.0,
- )
- # extract_long_term_memories may return either a list[Context]
- # (v2) or a {"contexts": [...], "session_skills": [...]} dict (v3).
- if isinstance(memories, dict):
- memories = memories.get("contexts", [])
- logger.info(f"Redo: extracted {len(memories)} memories from {archive_uri}")
- except Exception as e:
- logger.warning(f"Redo: memory extraction failed ({e}), falling back to queue")
-
- # 4. Always enqueue semantic processing as fallback
- await self._enqueue_semantic(
- uri=session_uri,
- context_type="memory",
- account_id=account_id,
- user_id=user_id,
- peer_id=user_id,
- role=role_str,
- )
-
- async def _enqueue_semantic(self, **params: Any) -> None:
- from openviking.storage.queuefs import get_queue_manager
- from openviking.storage.queuefs.semantic_msg import SemanticMsg
- from openviking.storage.queuefs.semantic_queue import SemanticQueue
-
- queue_manager = get_queue_manager()
- if queue_manager is None:
- logger.debug("No queue manager available, skipping enqueue_semantic")
- return
-
- uri = params.get("uri")
- if not uri:
- return
-
- msg = SemanticMsg(
- uri=uri,
- context_type=params.get("context_type", "resource"),
- account_id=params.get("account_id", "default"),
- user_id=params.get("user_id", "default"),
- peer_id=params.get("peer_id", "default"),
- role=params.get("role", "root"),
- )
- semantic_queue: SemanticQueue = queue_manager.get_queue(queue_manager.SEMANTIC) # type: ignore[assignment]
- await semantic_queue.enqueue(msg)
-
-
-# ---------------------------------------------------------------------------
-# Module-level singleton
-# ---------------------------------------------------------------------------
-
-_lock_manager: Optional[LockManager] = None
-
-
-def init_lock_manager(
- agfs: AGFSSyncClientProtocol,
- lock_timeout: float = 0.0,
- lock_expire: float = 300.0,
- redo_recovery_enabled: bool = True,
-) -> LockManager:
- global _lock_manager
- _lock_manager = LockManager(
- agfs=agfs,
- lock_timeout=lock_timeout,
- lock_expire=lock_expire,
- redo_recovery_enabled=redo_recovery_enabled,
- )
- return _lock_manager
-
-
-def get_lock_manager() -> LockManager:
- if _lock_manager is None:
- raise RuntimeError("LockManager not initialized. Call init_lock_manager() first.")
- return _lock_manager
-
-
-def reset_lock_manager() -> None:
- global _lock_manager
- _lock_manager = None
-
-
-async def release_all_locks() -> None:
- """Release all active lock handles. **Test-only utility.**"""
- if _lock_manager is None:
- return
- for handle in list((await _lock_manager.get_active_handles_async()).values()):
- await _lock_manager.release(handle)
diff --git a/openviking/storage/transaction/path_lock.py b/openviking/storage/transaction/path_lock.py
deleted file mode 100644
index 7b80c8dfb..000000000
--- a/openviking/storage/transaction/path_lock.py
+++ /dev/null
@@ -1,859 +0,0 @@
-import asyncio
-import hashlib
-import re
-import time
-from dataclasses import dataclass, field
-from typing import Any, Callable, Optional, Tuple
-
-from openviking.pyagfs import AGFSSyncClientProtocol, AsyncAGFSClient
-from openviking.pyagfs.async_client import fs_ctx_from_agfs_path
-from openviking.storage.internal_names import (
- MULTIWRITE_EXACT_LOCK_FILE_PREFIX,
- MULTIWRITE_PATH_LOCK_FILE,
-)
-from openviking.storage.transaction.lock_handle import LockOwner
-from openviking_cli.utils.logger import get_logger
-
-logger = get_logger(__name__)
-
-# Lock file name
-LOCK_FILE_NAME = MULTIWRITE_PATH_LOCK_FILE
-EXACT_LOCK_FILE_PREFIX = MULTIWRITE_EXACT_LOCK_FILE_PREFIX
-
-# Lock type constants
-LOCK_TYPE_EXACT = "E"
-LOCK_TYPE_TREE = "T"
-# Upgrade compatibility: old POINT/SUBTREE tokens are still treated as tree locks.
-_READ_ONLY_TREE_LOCK_TYPES = {"P", "S"}
-
-# Default poll interval when waiting for a lock (seconds)
-_POLL_INTERVAL = 0.1
-_WAIT_LOG_INTERVAL = 10.0
-_last_timeout_warning_at: dict[str, float] = {}
-
-
-@dataclass
-class LockRefreshResult:
- refreshed_paths: list[str] = field(default_factory=list)
- lost_paths: list[str] = field(default_factory=list)
- failed_paths: list[str] = field(default_factory=list)
-
-
-def _make_fencing_token(owner_id: str, lock_type: str = LOCK_TYPE_EXACT) -> str:
- return f"{owner_id}:{time.time_ns()}:{lock_type}"
-
-
-def _parse_fencing_token(token: str) -> Tuple[str, int, str]:
- known_types = {LOCK_TYPE_EXACT, LOCK_TYPE_TREE, *_READ_ONLY_TREE_LOCK_TYPES}
- if len(token) >= 2 and token[-2] == ":" and token[-1] in known_types:
- lock_type = LOCK_TYPE_TREE if token[-1] in _READ_ONLY_TREE_LOCK_TYPES else token[-1]
- rest = token[:-2]
- idx = rest.rfind(":")
- if idx >= 0:
- owner_id_part = rest[:idx]
- ts_part = rest[idx + 1 :]
- try:
- return owner_id_part, int(ts_part), lock_type
- except ValueError:
- pass
- return rest, 0, lock_type
-
- return token, 0, LOCK_TYPE_EXACT
-
-
-def _log_timeout_waiting(message: str) -> None:
- now = asyncio.get_running_loop().time()
- last_warning_at = _last_timeout_warning_at.get(message, 0.0)
- if not last_warning_at or now - last_warning_at >= _WAIT_LOG_INTERVAL:
- logger.warning(message)
- _last_timeout_warning_at[message] = now
-
-
-def _call_sync_agfs_with_ctx(
- method: Callable[..., Any], path: str, *args: Any, **kwargs: Any
-) -> Any:
- """Call a sync AGFS method with path-derived FsContext, falling back for legacy fakes."""
- try:
- return method(path, *args, **kwargs, ctx=fs_ctx_from_agfs_path(path))
- except TypeError as exc:
- if "unexpected keyword argument 'ctx'" not in str(exc):
- raise
- return method(path, *args, **kwargs)
-
-
-class PathLockEngine:
- def __init__(self, agfs_client: AGFSSyncClientProtocol, lock_expire: float = 300.0):
- self._agfs = agfs_client
- self._async_agfs = AsyncAGFSClient(agfs_client)
- self._lock_expire = lock_expire
-
- def _get_lock_path(self, path: str) -> str:
- path = path.rstrip("/") or "/"
- if path == "/":
- return f"/{LOCK_FILE_NAME}"
- return f"{path}/{LOCK_FILE_NAME}"
-
- def _is_existing_directory(self, path: str) -> bool:
- try:
- stat = _call_sync_agfs_with_ctx(self._agfs.stat, path.rstrip("/") or "/")
- except Exception:
- return False
- if isinstance(stat, dict):
- return stat.get("isDir") is True
- return getattr(stat, "isDir", None) is True
-
- async def _is_existing_directory_async(self, path: str) -> bool:
- try:
- stat = await self._async_agfs.stat(path.rstrip("/") or "/")
- except Exception:
- return False
- if isinstance(stat, dict):
- return stat.get("isDir") is True
- return getattr(stat, "isDir", None) is True
-
- async def _is_existing_path_async(self, path: str) -> bool:
- try:
- await self._async_agfs.stat(path.rstrip("/") or "/")
- return True
- except Exception:
- return False
-
- def _get_prefixed_exact_lock_path(self, path: str) -> str:
- path = path.rstrip("/") or "/"
- parent = self._get_parent_path(path)
- if not parent:
- return self._get_lock_path(path)
- name = path.rsplit("/", 1)[-1]
- safe_name = re.sub(r"[^A-Za-z0-9._-]+", "_", name).strip("._") or "path"
- safe_name = safe_name[:80]
- digest = hashlib.sha1(path.encode("utf-8")).hexdigest()[:16]
- return f"{parent}/{EXACT_LOCK_FILE_PREFIX}{safe_name}.{digest}"
-
- def _get_exact_lock_path(self, path: str) -> str:
- """Return the primary lock-file path for an exact path lock."""
- if self._is_existing_directory(path):
- return self._get_lock_path(path)
- return self._get_prefixed_exact_lock_path(path)
-
- def _get_exact_lock_paths(self, path: str) -> list[str]:
- """Return all lock-file paths that can protect this exact path."""
- primary = self._get_exact_lock_path(path)
- prefixed = self._get_prefixed_exact_lock_path(path)
- if primary == prefixed:
- return [primary]
- return [primary, prefixed]
-
- async def _get_exact_lock_path_async(self, path: str) -> str:
- """Async variant for acquire paths, where stat may be remote/blocking."""
- if await self._is_existing_directory_async(path):
- return self._get_lock_path(path)
- return self._get_prefixed_exact_lock_path(path)
-
- async def _get_exact_lock_paths_async(self, path: str) -> list[str]:
- primary = await self._get_exact_lock_path_async(path)
- prefixed = self._get_prefixed_exact_lock_path(path)
- if primary == prefixed:
- return [primary]
- return [primary, prefixed]
-
- async def _ensure_directory_exists_async(self, path: str):
- """Async variant for lock acquisition paths."""
- try:
- await self._async_agfs.stat(path)
- except Exception:
- try:
- parent = self._get_parent_path(path)
- if parent:
- await self._ensure_directory_exists_async(parent)
- await self._async_agfs.mkdir(path)
- logger.debug(f"Directory created: {path}")
- except Exception as e:
- if await self._is_existing_directory_async(path):
- logger.debug(f"Directory created concurrently: {path}")
- return True
- logger.warning(f"Failed to create directory {path}: {e}")
- return False
- return True
-
- def _get_parent_path(self, path: str) -> Optional[str]:
- path = path.rstrip("/")
- if "/" not in path:
- return None
- parent = path.rsplit("/", 1)[0]
- return parent if parent else None
-
- def _read_token(self, lock_path: str) -> Optional[str]:
- try:
- content = _call_sync_agfs_with_ctx(self._agfs.read, lock_path)
- if isinstance(content, bytes):
- token = content.decode("utf-8").strip()
- else:
- token = str(content).strip()
- return token if token else None
- except Exception:
- return None
-
- async def _read_token_async(self, lock_path: str) -> Optional[str]:
- try:
- content = await self._async_agfs.read(lock_path)
- if isinstance(content, bytes):
- token = content.decode("utf-8").strip()
- else:
- token = str(content).strip()
- return token if token else None
- except Exception:
- return None
-
- def _read_owner_and_type(self, lock_path: str) -> Tuple[Optional[str], Optional[str]]:
- token = self._read_token(lock_path)
- if token is None:
- return None, None
- owner_id, _, lock_type = _parse_fencing_token(token)
- return owner_id, lock_type
-
- async def _read_owner_and_type_async(
- self, lock_path: str
- ) -> Tuple[Optional[str], Optional[str]]:
- token = await self._read_token_async(lock_path)
- if token is None:
- return None, None
- owner_id, _, lock_type = _parse_fencing_token(token)
- return owner_id, lock_type
-
- def is_lock_owned_by(self, lock_path: str, owner_id: str) -> bool:
- current_owner_id, _ = self._read_owner_and_type(lock_path)
- return current_owner_id == owner_id
-
- async def is_lock_owned_by_async(self, lock_path: str, owner_id: str) -> bool:
- current_owner_id, _ = await self._read_owner_and_type_async(lock_path)
- return current_owner_id == owner_id
-
- async def _is_lock_owned_by_async(self, lock_path: str, owner_id: str) -> bool:
- return await self.is_lock_owned_by_async(lock_path, owner_id)
-
- def is_locked(self, path: str, ignore_stale: bool = True) -> bool:
- """Check whether *path* is currently locked.
-
- Detection rules (aligned with conflict checks in the acquire flow):
- - The path itself has a valid .path.ovlock; or
- - The path has a valid exact-path lock in the parent directory; or
- - Any ancestor directory holds a TREE lock.
-
- Args:
- path: Path to check (already converted to AGFS internal path).
- ignore_stale: Whether to ignore expired (stale) locks. Defaults
- to True to stay consistent with the acquire flow: stale
- locks will be cleaned up by the next acquirer, so they are
- not considered as held here.
- """
- # 1. Lock on the path itself
- own_lock_path = self._get_lock_path(path)
- token = self._read_token(own_lock_path)
- if token is not None:
- if not (ignore_stale and self.is_lock_stale(own_lock_path, self._lock_expire)):
- return True
-
- # 2. ExactPathLock for file, directory name, or not-yet-created paths
- for exact_lock_path in self._get_exact_lock_paths(path):
- if exact_lock_path == own_lock_path:
- continue
- exact_token = self._read_token(exact_lock_path)
- if exact_token is not None:
- if not (ignore_stale and self.is_lock_stale(exact_lock_path, self._lock_expire)):
- return True
-
- # 3. Ancestor TREE locks
- parent = self._get_parent_path(path)
- while parent:
- ancestor_lock = self._get_lock_path(parent)
- ancestor_token = self._read_token(ancestor_lock)
- if ancestor_token is not None:
- _, _, lock_type = _parse_fencing_token(ancestor_token)
- if lock_type == LOCK_TYPE_TREE and not (
- ignore_stale and self.is_lock_stale(ancestor_lock, self._lock_expire)
- ):
- return True
- parent = self._get_parent_path(parent)
-
- return False
-
- async def is_locked_async(self, path: str, ignore_stale: bool = True) -> bool:
- """Async variant of is_locked for request/background paths."""
- own_lock_path = self._get_lock_path(path)
- token = await self._read_token_async(own_lock_path)
- if token is not None:
- if not (
- ignore_stale and await self._is_lock_stale_async(own_lock_path, self._lock_expire)
- ):
- return True
-
- for exact_lock_path in await self._get_exact_lock_paths_async(path):
- if exact_lock_path == own_lock_path:
- continue
- exact_token = await self._read_token_async(exact_lock_path)
- if exact_token is not None:
- if not (
- ignore_stale
- and await self._is_lock_stale_async(exact_lock_path, self._lock_expire)
- ):
- return True
-
- parent = self._get_parent_path(path)
- while parent:
- ancestor_lock = self._get_lock_path(parent)
- ancestor_token = await self._read_token_async(ancestor_lock)
- if ancestor_token is not None:
- _, _, lock_type = _parse_fencing_token(ancestor_token)
- if lock_type == LOCK_TYPE_TREE and not (
- ignore_stale
- and await self._is_lock_stale_async(ancestor_lock, self._lock_expire)
- ):
- return True
- parent = self._get_parent_path(parent)
-
- return False
-
- def collect_lost_owner_locks(self, owner: LockOwner) -> list[str]:
- lost_paths: list[str] = []
- for lock_path in list(owner.locks):
- if not self.is_lock_owned_by(lock_path, owner.id):
- lost_paths.append(lock_path)
- return lost_paths
-
- async def collect_lost_owner_locks_async(self, owner: LockOwner) -> list[str]:
- lost_paths: list[str] = []
- for lock_path in list(owner.locks):
- if not await self._is_lock_owned_by_async(lock_path, owner.id):
- lost_paths.append(lock_path)
- return lost_paths
-
- async def _is_locked_by_other(self, lock_path: str, owner_id: str) -> bool:
- token = await self._read_token_async(lock_path)
- if token is None:
- return False
- lock_owner, _, _ = _parse_fencing_token(token)
- return lock_owner != owner_id
-
- async def _create_lock_file(
- self, lock_path: str, owner_id: str, lock_type: str = LOCK_TYPE_EXACT
- ) -> None:
- token = _make_fencing_token(owner_id, lock_type)
- await self._async_agfs.write(lock_path, token.encode("utf-8"))
-
- async def _owned_lock_type(self, path: str, owner: LockOwner) -> Optional[str]:
- lock_path = self._get_lock_path(path)
- return await self._owned_lock_type_for_lock_path(lock_path, owner)
-
- async def _owned_lock_type_for_lock_path(
- self, lock_path: str, owner: LockOwner
- ) -> Optional[str]:
- if lock_path not in owner.locks:
- return None
- token = await self._read_token_async(lock_path)
- if token is None:
- return None
- lock_owner, _, lock_type = _parse_fencing_token(token)
- if lock_owner != owner.id:
- return None
- return lock_type
-
- async def _has_owned_ancestor_tree(self, path: str, owner: LockOwner) -> bool:
- current = path.rstrip("/")
- while current:
- if await self._owned_lock_type(current, owner) == LOCK_TYPE_TREE:
- return True
- current = self._get_parent_path(current) or ""
- return False
-
- async def _remove_lock_file(self, lock_path: str) -> bool:
- try:
- await self._async_agfs.rm(lock_path)
- return True
- except Exception as e:
- if "not found" in str(e).lower():
- return True
- return False
-
- def is_lock_stale(self, lock_path: str, expire_seconds: float = 300.0) -> bool:
- token = self._read_token(lock_path)
- if token is None:
- return True
- _, ts, _ = _parse_fencing_token(token)
- if ts == 0:
- return True
- age = (time.time_ns() - ts) / 1e9
- return age > expire_seconds
-
- async def _is_lock_stale_async(self, lock_path: str, expire_seconds: float = 300.0) -> bool:
- token = await self._read_token_async(lock_path)
- if token is None:
- return True
- _, ts, _ = _parse_fencing_token(token)
- if ts == 0:
- return True
- age = (time.time_ns() - ts) / 1e9
- return age > expire_seconds
-
- async def _check_ancestors_for_tree(self, path: str, exclude_owner_id: str) -> Optional[str]:
- parent = self._get_parent_path(path)
- while parent:
- lock_path = self._get_lock_path(parent)
- token = await self._read_token_async(lock_path)
- if token is not None:
- owner_id, _, lock_type = _parse_fencing_token(token)
- if owner_id != exclude_owner_id and lock_type == LOCK_TYPE_TREE:
- return lock_path
- parent = self._get_parent_path(parent)
- return None
-
- async def _check_path_lock(self, path: str, exclude_owner_id: str) -> Optional[str]:
- lock_path = self._get_lock_path(path)
- token = await self._read_token_async(lock_path)
- if token is None:
- return None
- owner_id, _, _ = _parse_fencing_token(token)
- if owner_id != exclude_owner_id:
- return lock_path
- return None
-
- async def _check_exact_path_lock(self, path: str, exclude_owner_id: str) -> Optional[str]:
- for lock_path in await self._get_exact_lock_paths_async(path):
- token = await self._read_token_async(lock_path)
- if token is None:
- continue
- owner_id, _, _ = _parse_fencing_token(token)
- if owner_id != exclude_owner_id:
- return lock_path
- return None
-
- async def _scan_descendants_for_locks(self, path: str, exclude_owner_id: str) -> Optional[str]:
- try:
- try:
- stat = await self._async_agfs.stat(path)
- except Exception:
- return None
- if isinstance(stat, dict) and not stat.get("isDir", False):
- return None
- if not isinstance(stat, dict) and getattr(stat, "isDir", None) is not True:
- return None
- entries = await self._async_agfs.ls(path)
- if not isinstance(entries, list):
- return None
- for entry in entries:
- if not isinstance(entry, dict):
- continue
- name = entry.get("name", "")
- if not name or name in (".", ".."):
- continue
- entry_path = f"{path.rstrip('/')}/{name}"
- if name.startswith(EXACT_LOCK_FILE_PREFIX):
- token = await self._read_token_async(entry_path)
- if token is not None:
- owner_id, _, _ = _parse_fencing_token(token)
- if owner_id != exclude_owner_id:
- return entry_path
- continue
- if not entry.get("isDir", False):
- continue
- subdir = entry_path
- subdir_lock = self._get_lock_path(subdir)
- token = await self._read_token_async(subdir_lock)
- if token is not None:
- owner_id, _, _ = _parse_fencing_token(token)
- if owner_id != exclude_owner_id:
- return subdir_lock
- result = await self._scan_descendants_for_locks(subdir, exclude_owner_id)
- if result:
- return result
- except Exception as e:
- logger.warning(f"Failed to scan descendants of {path}: {e}")
- return None
-
- async def acquire_exact_path(
- self, path: str, owner: LockOwner, timeout: Optional[float] = 0.0
- ) -> bool:
- """Acquire a short lock for one exact path.
-
- It conflicts with:
- - another ExactPathLock on the same path;
- - any ancestor TREE lock;
- - a TREE lock on the exact same path.
-
- It does not conflict with sibling exact paths.
- """
- owner_id = owner.id
- lock_path = await self._get_exact_lock_path_async(path)
- if lock_path in owner.locks and await self._is_lock_owned_by_async(lock_path, owner_id):
- owner.add_lock(lock_path)
- logger.debug(f"[EXACT] Reusing owned exact lock on: {path}")
- return True
- if await self._has_owned_ancestor_tree(path, owner):
- logger.debug(f"[EXACT] Reusing owned ancestor TREE lock on: {path}")
- return True
- had_no_timeout = timeout is None
- if had_no_timeout:
- timeout = self._lock_expire
- deadline = asyncio.get_running_loop().time() + timeout
- wait_start = asyncio.get_running_loop().time()
- next_wait_log_at = wait_start + _WAIT_LOG_INTERVAL
-
- while True:
- existing_exact_lock = await self._check_exact_path_lock(path, owner_id)
- if existing_exact_lock:
- if await self._is_lock_stale_async(existing_exact_lock, self._lock_expire):
- logger.warning(f"[EXACT] Removing stale exact lock: {existing_exact_lock}")
- await self._remove_lock_file(existing_exact_lock)
- continue
- if asyncio.get_running_loop().time() >= deadline:
- _log_timeout_waiting(f"[EXACT] Timeout waiting for exact lock on: {path}")
- return False
- now = asyncio.get_running_loop().time()
- if had_no_timeout and now >= next_wait_log_at:
- logger.info(
- f"[EXACT] Still waiting for lock on: {path} "
- f"(waited={now - wait_start:.1f}s)"
- )
- next_wait_log_at = now + _WAIT_LOG_INTERVAL
- await asyncio.sleep(_POLL_INTERVAL)
- continue
-
- same_path_lock = self._get_lock_path(path)
- if same_path_lock != lock_path:
- token = await self._read_token_async(same_path_lock)
- if token is not None:
- lock_owner, _, _ = _parse_fencing_token(token)
- if lock_owner != owner_id:
- if await self._is_lock_stale_async(same_path_lock, self._lock_expire):
- logger.warning(f"[EXACT] Removing stale lock: {same_path_lock}")
- await self._remove_lock_file(same_path_lock)
- continue
- if asyncio.get_running_loop().time() >= deadline:
- _log_timeout_waiting(f"[EXACT] Timeout waiting for lock: {path}")
- return False
- await asyncio.sleep(_POLL_INTERVAL)
- continue
-
- ancestor_conflict = await self._check_ancestors_for_tree(path, owner_id)
- if ancestor_conflict:
- if await self._is_lock_stale_async(ancestor_conflict, self._lock_expire):
- logger.warning(
- f"[EXACT] Removing stale ancestor TREE lock: {ancestor_conflict}"
- )
- await self._remove_lock_file(ancestor_conflict)
- continue
- if asyncio.get_running_loop().time() >= deadline:
- _log_timeout_waiting(
- f"[EXACT] Timeout waiting for ancestor TREE lock: {ancestor_conflict}"
- )
- return False
- now = asyncio.get_running_loop().time()
- if had_no_timeout and now >= next_wait_log_at:
- logger.info(
- f"[EXACT] Still waiting for ancestor TREE lock: {ancestor_conflict} "
- f"(path={path}, waited={now - wait_start:.1f}s)"
- )
- next_wait_log_at = now + _WAIT_LOG_INTERVAL
- await asyncio.sleep(_POLL_INTERVAL)
- continue
-
- parent = self._get_parent_path(path)
- if (
- lock_path != self._get_lock_path(path)
- and parent
- and not await self._ensure_directory_exists_async(parent)
- ):
- logger.warning(f"[EXACT] Failed to ensure parent directory exists: {parent}")
- return False
-
- try:
- await self._create_lock_file(lock_path, owner_id, LOCK_TYPE_EXACT)
- except Exception as e:
- logger.error(f"[EXACT] Failed to create lock file: {e}")
- return False
-
- if not await self._is_lock_owned_by_async(lock_path, owner_id):
- logger.debug(f"[EXACT] Lost lock write race on: {path}")
- if asyncio.get_running_loop().time() >= deadline:
- return False
- await asyncio.sleep(_POLL_INTERVAL)
- continue
-
- conflict_after = await self._check_path_lock(path, owner_id)
- if conflict_after == lock_path:
- conflict_after = None
- if not conflict_after:
- conflict_after = await self._check_ancestors_for_tree(path, owner_id)
- if conflict_after:
- their_token = await self._read_token_async(conflict_after)
- if their_token:
- their_owner_id, their_ts, _ = _parse_fencing_token(their_token)
- my_token = await self._read_token_async(lock_path)
- _, my_ts, _ = (
- _parse_fencing_token(my_token) if my_token else ("", 0, LOCK_TYPE_EXACT)
- )
- if (my_ts, owner_id) > (their_ts, their_owner_id):
- logger.debug(f"[EXACT] Backing off (livelock guard) on {path}")
- if await self._is_lock_owned_by_async(lock_path, owner_id):
- await self._remove_lock_file(lock_path)
- if asyncio.get_running_loop().time() >= deadline:
- if await self._is_lock_owned_by_async(lock_path, owner_id):
- await self._remove_lock_file(lock_path)
- return False
- now = asyncio.get_running_loop().time()
- if had_no_timeout and now >= next_wait_log_at:
- logger.info(
- f"[EXACT] Still waiting after conflict check on: {path} "
- f"(waited={now - wait_start:.1f}s)"
- )
- next_wait_log_at = now + _WAIT_LOG_INTERVAL
- await asyncio.sleep(_POLL_INTERVAL)
- continue
-
- if not await self._is_lock_owned_by_async(lock_path, owner_id):
- logger.debug(f"[EXACT] Lock ownership verification failed: {path}")
- if asyncio.get_running_loop().time() >= deadline:
- return False
- now = asyncio.get_running_loop().time()
- if had_no_timeout and now >= next_wait_log_at:
- logger.info(
- f"[EXACT] Still waiting for lock ownership verification: {path} "
- f"(waited={now - wait_start:.1f}s)"
- )
- next_wait_log_at = now + _WAIT_LOG_INTERVAL
- await asyncio.sleep(_POLL_INTERVAL)
- continue
-
- owner.add_lock(lock_path)
- logger.debug(f"[EXACT] Lock acquired: {lock_path}")
- return True
-
- async def acquire_tree(
- self, path: str, owner: LockOwner, timeout: Optional[float] = 0.0
- ) -> bool:
- owner_id = owner.id
- default_lock_path = self._get_lock_path(path)
- lock_path = await self._get_exact_lock_path_async(path)
- if lock_path != default_lock_path and not await self._is_existing_path_async(path):
- lock_path = default_lock_path
-
- owned_lock_type = await self._owned_lock_type_for_lock_path(lock_path, owner)
- if owned_lock_type == LOCK_TYPE_TREE:
- owner.add_lock(lock_path)
- logger.debug(f"[TREE] Reusing owned TREE lock on: {path}")
- return True
- if await self._has_owned_ancestor_tree(path, owner):
- logger.debug(f"[TREE] Reusing owned ancestor TREE lock on: {path}")
- return True
- had_no_timeout = timeout is None
- if had_no_timeout:
- timeout = self._lock_expire
- deadline = asyncio.get_running_loop().time() + timeout
- wait_start = asyncio.get_running_loop().time()
- next_wait_log_at = wait_start + _WAIT_LOG_INTERVAL
-
- while True:
- if await self._is_locked_by_other(lock_path, owner_id):
- if await self._is_lock_stale_async(lock_path, self._lock_expire):
- logger.warning(f"[TREE] Removing stale lock: {lock_path}")
- await self._remove_lock_file(lock_path)
- continue
- if asyncio.get_running_loop().time() >= deadline:
- _log_timeout_waiting(f"[TREE] Timeout waiting for lock on: {path}")
- return False
- now = asyncio.get_running_loop().time()
- if had_no_timeout and now >= next_wait_log_at:
- logger.info(
- f"[TREE] Still waiting for lock on: {path} (waited={now - wait_start:.1f}s)"
- )
- next_wait_log_at = now + _WAIT_LOG_INTERVAL
- await asyncio.sleep(_POLL_INTERVAL)
- continue
-
- # Check ancestor paths for TREE locks held by other owners
- ancestor_conflict = await self._check_ancestors_for_tree(path, owner_id)
- if ancestor_conflict:
- if await self._is_lock_stale_async(ancestor_conflict, self._lock_expire):
- logger.warning(f"[TREE] Removing stale ancestor TREE lock: {ancestor_conflict}")
- await self._remove_lock_file(ancestor_conflict)
- continue
- if asyncio.get_running_loop().time() >= deadline:
- _log_timeout_waiting(
- f"[TREE] Timeout waiting for ancestor TREE lock: {ancestor_conflict}"
- )
- return False
- now = asyncio.get_running_loop().time()
- if had_no_timeout and now >= next_wait_log_at:
- logger.info(
- f"[TREE] Still waiting for ancestor TREE lock: {ancestor_conflict} "
- f"(path={path}, waited={now - wait_start:.1f}s)"
- )
- next_wait_log_at = now + _WAIT_LOG_INTERVAL
- await asyncio.sleep(_POLL_INTERVAL)
- continue
-
- exact_conflict = await self._check_exact_path_lock(path, owner_id)
- if exact_conflict:
- if await self._is_lock_stale_async(exact_conflict, self._lock_expire):
- logger.warning(f"[TREE] Removing stale exact lock: {exact_conflict}")
- await self._remove_lock_file(exact_conflict)
- continue
- if asyncio.get_running_loop().time() >= deadline:
- _log_timeout_waiting(f"[TREE] Timeout waiting for exact lock: {exact_conflict}")
- return False
- await asyncio.sleep(_POLL_INTERVAL)
- continue
-
- desc_conflict = await self._scan_descendants_for_locks(path, owner_id)
- if desc_conflict:
- if await self._is_lock_stale_async(desc_conflict, self._lock_expire):
- logger.warning(f"[TREE] Removing stale descendant lock: {desc_conflict}")
- await self._remove_lock_file(desc_conflict)
- continue
- if asyncio.get_running_loop().time() >= deadline:
- _log_timeout_waiting(
- f"[TREE] Timeout waiting for descendant lock: {desc_conflict}"
- )
- return False
- now = asyncio.get_running_loop().time()
- if had_no_timeout and now >= next_wait_log_at:
- logger.info(
- f"[TREE] Still waiting for descendant lock: {desc_conflict} "
- f"(path={path}, waited={now - wait_start:.1f}s)"
- )
- next_wait_log_at = now + _WAIT_LOG_INTERVAL
- await asyncio.sleep(_POLL_INTERVAL)
- continue
-
- if not await self._ensure_directory_exists_async(path):
- logger.warning(f"[TREE] Failed to ensure directory exists: {path}")
- return False
-
- try:
- await self._create_lock_file(lock_path, owner_id, LOCK_TYPE_TREE)
- except Exception as e:
- logger.error(f"[TREE] Failed to create lock file: {e}")
- return False
-
- backed_off = False
- conflict_after = await self._scan_descendants_for_locks(path, owner_id)
- if not conflict_after:
- conflict_after = await self._check_exact_path_lock(path, owner_id)
- if not conflict_after:
- conflict_after = await self._check_ancestors_for_tree(path, owner_id)
- if conflict_after:
- their_token = await self._read_token_async(conflict_after)
- if their_token:
- their_owner_id, their_ts, _ = _parse_fencing_token(their_token)
- my_token = await self._read_token_async(lock_path)
- _, my_ts, _ = (
- _parse_fencing_token(my_token) if my_token else ("", 0, LOCK_TYPE_TREE)
- )
- if (my_ts, owner_id) > (their_ts, their_owner_id):
- logger.debug(f"[TREE] Backing off (livelock guard) on {path}")
- await self._remove_lock_file(lock_path)
- backed_off = True
- if asyncio.get_running_loop().time() >= deadline:
- if not backed_off:
- await self._remove_lock_file(lock_path)
- return False
- now = asyncio.get_running_loop().time()
- if had_no_timeout and now >= next_wait_log_at:
- logger.info(
- f"[TREE] Still waiting after conflict check on: {path} "
- f"(waited={now - wait_start:.1f}s)"
- )
- next_wait_log_at = now + _WAIT_LOG_INTERVAL
- await asyncio.sleep(_POLL_INTERVAL)
- continue
-
- if not await self._is_lock_owned_by_async(lock_path, owner_id):
- logger.debug(f"[TREE] Lock ownership verification failed: {path}")
- if asyncio.get_running_loop().time() >= deadline:
- return False
- now = asyncio.get_running_loop().time()
- if had_no_timeout and now >= next_wait_log_at:
- logger.info(
- f"[TREE] Still waiting for lock ownership verification: {path} "
- f"(waited={now - wait_start:.1f}s)"
- )
- next_wait_log_at = now + _WAIT_LOG_INTERVAL
- await asyncio.sleep(_POLL_INTERVAL)
- continue
-
- owner.add_lock(lock_path)
- logger.debug(f"[TREE] Lock acquired: {lock_path}")
- return True
-
- async def acquire_mv(
- self,
- src_path: str,
- dst_path: str,
- owner: LockOwner,
- timeout: Optional[float] = 0.0,
- src_is_dir: bool = True,
- ) -> bool:
- """Acquire locks for a move operation.
-
- Args:
- src_path: Source path to lock.
- dst_path: Destination path to lock.
- owner: Lock owner handle.
- timeout: Maximum seconds to wait for each lock.
- src_is_dir: Whether the source is a directory (TREE lock)
- or a file (ExactPathLock on source and destination path).
- """
- if src_is_dir:
- if not await self.acquire_tree(src_path, owner, timeout=timeout):
- logger.warning(f"[MV] Failed to acquire TREE lock on source: {src_path}")
- return False
- if not await self.acquire_exact_path(dst_path, owner, timeout=timeout):
- logger.warning(f"[MV] Failed to acquire exact lock on destination: {dst_path}")
- await self.release(owner)
- return False
- else:
- if not await self.acquire_exact_path(src_path, owner, timeout=timeout):
- logger.warning(f"[MV] Failed to acquire exact lock on source: {src_path}")
- return False
- if not await self.acquire_exact_path(dst_path, owner, timeout=timeout):
- logger.warning(f"[MV] Failed to acquire exact lock on destination: {dst_path}")
- await self.release(owner)
- return False
-
- logger.debug(f"[MV] Locks acquired: {src_path} -> {dst_path}")
- return True
-
- async def refresh(self, owner: LockOwner) -> LockRefreshResult:
- """Rewrite all lock file timestamps to prevent stale cleanup."""
- result = LockRefreshResult()
- for lock_path in list(owner.locks):
- parsed_owner_id, lock_type = await self._read_owner_and_type_async(lock_path)
- if parsed_owner_id != owner.id or lock_type is None:
- result.lost_paths.append(lock_path)
- continue
- new_token = _make_fencing_token(owner.id, lock_type)
- try:
- await self._async_agfs.write(lock_path, new_token.encode("utf-8"))
- result.refreshed_paths.append(lock_path)
- except Exception as e:
- logger.warning(f"Failed to refresh lock {lock_path}: {e}")
- result.failed_paths.append(lock_path)
- return result
-
- async def release(self, owner: LockOwner) -> None:
- lock_count = len(owner.locks)
- released_count = 0
- for lock_path in reversed(list(owner.locks)):
- if await self._is_lock_owned_by_async(lock_path, owner.id):
- await self._remove_lock_file(lock_path)
- released_count += 1
- owner.remove_lock(lock_path)
-
- logger.debug(f"Released {released_count}/{lock_count} locks for owner {owner.id}")
-
- async def release_selected(self, owner: LockOwner, lock_paths: list[str]) -> None:
- for lock_path in reversed(lock_paths):
- if lock_path not in owner.locks:
- continue
- if await self._is_lock_owned_by_async(lock_path, owner.id):
- await self._remove_lock_file(lock_path)
- owner.remove_lock(lock_path)
diff --git a/openviking/storage/viking_fs.py b/openviking/storage/viking_fs.py
index e9ebfdaf7..bf4bdc669 100644
--- a/openviking/storage/viking_fs.py
+++ b/openviking/storage/viking_fs.py
@@ -22,7 +22,7 @@ import time
from contextlib import contextmanager
from dataclasses import dataclass, field
from datetime import datetime, timezone
-from typing import TYPE_CHECKING, Any, Awaitable, Callable, Dict, List, Optional, TypeVar, Union
+from typing import TYPE_CHECKING, Any, Dict, List, Optional, TypeVar, Union
from openviking.core.context import ContextLevel
from openviking.core.namespace import (
@@ -49,10 +49,7 @@ from openviking.resource.watch_storage import is_watch_task_control_uri
from openviking.server.error_mapping import is_not_found_error, map_exception
from openviking.server.identity import RequestContext, Role
from openviking.storage.expr import And, PathScope, RawDSL
-from openviking.storage.internal_names import (
- MULTIWRITE_PATH_LOCK_FILE,
- STORAGE_INTERNAL_ENTRY_NAMES,
-)
+from openviking.storage.internal_names import STORAGE_INTERNAL_ENTRY_NAMES
from openviking.telemetry import get_current_telemetry
from openviking.utils.image_search import build_multimodal_embedding_input
from openviking.utils.time_utils import format_iso8601, get_current_timestamp, parse_iso_datetime
@@ -69,7 +66,6 @@ from openviking_cli.utils.logger import get_logger
from openviking_cli.utils.uri import VikingURI
if TYPE_CHECKING:
- from openviking.storage.transaction.lock_handle import LockHandle
from openviking.storage.viking_vector_index_backend import VikingVectorIndexBackend
from openviking_cli.utils.config import GrepConfig, RerankConfig, RetrievalConfig
@@ -423,38 +419,6 @@ class VikingFS:
digest = hashlib.sha256(relative_path.encode("utf-8")).hexdigest()
return f"{mount_prefix}{temp_root}/{digest}.encrypt"
- def _encrypted_write_lock_paths(self, path: str) -> List[str]:
- """Return the final and temp paths protected by the encrypted write protocol."""
- return [path, self._encrypted_temp_path(path)]
-
- async def _run_with_encrypted_write_lock(
- self,
- path: str,
- operation: Callable[[], Awaitable[_T]],
- lock_handle: Optional["LockHandle"] = None,
- ) -> _T:
- """Run a write operation under a dual-path exact lock when encryption is enabled."""
- if self._encryptor is None:
- return await operation()
-
- from openviking.storage.transaction import LockContext, get_lock_manager
-
- async with LockContext(
- get_lock_manager(),
- self._encrypted_write_lock_paths(path),
- lock_mode="exact",
- # Encrypted writes lock both the final path and the deterministic
- # staging path under `.encrypt_stage`. Keeping the global default
- # timeout at 0 is still desirable for ordinary path locks, but
- # this specific dual-path write is much more exposed to short-lived
- # contention between concurrent writers. A small 1-second wait here
- # lets us ride out transient conflicts without broadening lock
- # behavior for unrelated call sites.
- timeout=1.0,
- handle=lock_handle,
- ):
- return await operation()
-
def _ensure_access(self, uri: str, ctx: Optional[RequestContext]) -> None:
real_ctx = self._ctx_or_default(ctx)
normalized_uri, _ = self._normalized_uri_parts(uri)
@@ -595,20 +559,39 @@ class VikingFS:
# Encryption (when configured) happens inside the ragfs layer keyed by account_id.
return await self._async_agfs.write(path, data)
+ def _pathlock_fs_ctx(
+ self,
+ ctx: Optional[RequestContext],
+ lease_ref: Optional[Dict[str, Any] | str],
+ ) -> Dict[str, str] | None:
+ """Build an AGFS fs_ctx carrying account_id and an opaque pathlock lease_ref."""
+ if lease_ref is None:
+ return None
+ if isinstance(lease_ref, str):
+ ref = lease_ref
+ elif isinstance(lease_ref, dict):
+ ref = lease_ref.get("lease_ref")
+ else:
+ raise ValueError("lease_ref must be a non-empty string or lease dictionary")
+ if not isinstance(ref, str) or not ref:
+ raise ValueError("lease_ref must contain a non-empty lease_ref")
+ return {"account_id": self._ctx_or_default(ctx).account_id, "lease_ref": ref}
+
async def mkdir(
self,
uri: str,
mode: str = "755",
exist_ok: bool = False,
ctx: Optional[RequestContext] = None,
+ lease_ref: Dict[str, Any] | None = None,
) -> None:
"""Create directory."""
self._ensure_mutable_access(uri, ctx)
path = self._uri_to_path(uri, ctx=ctx)
# Always ensure parent directories exist before creating this directory
- await self._ensure_parent_dirs(path, ctx=ctx)
+ await self._ensure_parent_dirs(path, ctx=ctx, lease_ref=lease_ref)
try:
- await self._async_agfs.mkdir(path)
+ await self._async_agfs.mkdir(path, fs_ctx=self._pathlock_fs_ctx(ctx, lease_ref))
except Exception as exc:
message = str(exc).lower()
already_exists = "exist" in message or "already" in message
@@ -620,7 +603,7 @@ class VikingFS:
uri: str,
recursive: bool = False,
ctx: Optional[RequestContext] = None,
- lock_handle: Optional["LockHandle"] = None,
+ lease_ref: Dict[str, Any] | None = None,
) -> Dict[str, Any]:
"""Delete file/directory + recursively update vector index.
@@ -636,7 +619,6 @@ class VikingFS:
of nodes deleted from vector index.
"""
from openviking.storage.errors import LockAcquisitionError, ResourceBusyError
- from openviking.storage.transaction import LockContext, get_lock_manager
self._ensure_delete_access(uri, ctx)
path = self._uri_to_path(uri, ctx=ctx)
@@ -682,61 +664,62 @@ class VikingFS:
f"Cannot remove directory without --recursive: {uri}",
details={"resource": uri, "expected_flag": "recursive"},
)
- lock_paths = [path]
- lock_mode = "tree"
+ lock_method = self._async_agfs.pathlock_acquire_tree
else:
- lock_paths = [path]
- lock_mode = "exact"
+ lock_method = self._async_agfs.pathlock_acquire_exact
+
+ lease = lease_ref
+ if lease is None:
+ try:
+ lease = await lock_method(path)
+ except LockAcquisitionError:
+ raise ResourceBusyError(f"Resource is being processed: {uri}", uri=uri)
try:
- async with LockContext(
- get_lock_manager(),
- lock_paths,
- lock_mode=lock_mode,
- handle=lock_handle,
- ):
- uris_to_delete = (
- await self._collect_uris(path, recursive, ctx=ctx) if is_dir else []
+ uris_to_delete = await self._collect_uris(path, recursive, ctx=ctx) if is_dir else []
+ uris_to_delete.append(target_uri)
+ real_ctx = self._ctx_or_default(ctx)
+ estimated_count = await _estimate_deleted_count(path, real_ctx)
+ await self._delete_from_vector_store(uris_to_delete, ctx=ctx)
+ try:
+ result = await self._async_agfs.rm(
+ path,
+ recursive=recursive,
+ fs_ctx=self._pathlock_fs_ctx(ctx, lease),
)
- uris_to_delete.append(target_uri)
- real_ctx = self._ctx_or_default(ctx)
- estimated_count = await _estimate_deleted_count(path, real_ctx)
- await self._delete_from_vector_store(uris_to_delete, ctx=ctx)
- try:
- result = await self._async_agfs.rm(path, recursive=recursive)
- except AGFSDirectoryNotEmptyError:
+ except AGFSDirectoryNotEmptyError:
+ raise FailedPreconditionError(
+ f"Directory not empty: {uri}. Use recursive=True to delete non-empty directories."
+ )
+ except RuntimeError as e:
+ # Fallback for older versions without typed exceptions
+ if _is_directory_not_empty_error(str(e)):
raise FailedPreconditionError(
f"Directory not empty: {uri}. Use recursive=True to delete non-empty directories."
)
- except RuntimeError as e:
- # Fallback for older versions without typed exceptions
- if _is_directory_not_empty_error(str(e)):
- raise FailedPreconditionError(
- f"Directory not empty: {uri}. Use recursive=True to delete non-empty directories."
- )
- raise
- # Add estimated_deleted_count to the result
- if isinstance(result, dict):
- result["estimated_deleted_count"] = estimated_count
- else:
- result = {"estimated_deleted_count": estimated_count}
- return result
- except LockAcquisitionError:
- raise ResourceBusyError(f"Resource is being processed: {uri}", uri=uri)
+ raise
+ # Add estimated_deleted_count to the result
+ if isinstance(result, dict):
+ result["estimated_deleted_count"] = estimated_count
+ else:
+ result = {"estimated_deleted_count": estimated_count}
+ return result
+ finally:
+ if lease_ref is None:
+ await self._async_agfs.pathlock_release(lease)
async def mv(
self,
old_uri: str,
new_uri: str,
ctx: Optional[RequestContext] = None,
- lock_handle: Optional["LockHandle"] = None,
+ lease_ref: Dict[str, Any] | None = None,
) -> Dict[str, Any]:
- """Move file/directory + recursively update vector index.
+ """Move file/directory while extending an optional outer pathlock lease.
Implemented as cp + rm to avoid lock files being carried by FS mv.
On VectorDB update failure the copy is cleaned up so the source stays intact.
"""
- from openviking.storage.transaction import LockContext, get_lock_manager
self._ensure_mutable_access(old_uri, ctx)
# mv is implemented as copy + recursive rm of the source (see the
@@ -787,25 +770,24 @@ class VikingFS:
old_uri = canonicalize_uri(old_uri, real_ctx)
new_uri = canonicalize_uri(new_uri, real_ctx)
- lock_context = (
- LockContext(
- get_lock_manager(),
- [old_path],
- lock_mode="mv",
- mv_dst_path=new_path,
- src_is_dir=True,
- handle=lock_handle,
+ if is_dir:
+ lease = await self._async_agfs.pathlock_acquire_batch(
+ [
+ {"path": old_path, "kind": "tree"},
+ {"path": new_path, "kind": "exact"},
+ ],
+ owner_lease_ref=lease_ref,
)
- if is_dir
- else LockContext(
- get_lock_manager(),
- [old_path, new_path],
- lock_mode="exact",
- handle=lock_handle,
+ else:
+ lease = await self._async_agfs.pathlock_acquire_batch(
+ [
+ {"path": old_path, "kind": "exact"},
+ {"path": new_path, "kind": "exact"},
+ ],
+ owner_lease_ref=lease_ref,
)
- )
- async with lock_context as active_lock_handle:
+ try:
uris_to_move = (
await self._collect_uris(old_path, recursive=True, ctx=ctx) if is_dir else []
)
@@ -824,7 +806,7 @@ class VikingFS:
is_dir=is_dir,
is_temp=is_temp,
ctx=ctx,
- lock_handle=active_lock_handle,
+ lease_ref=lease,
)
except Exception as e:
if "not found" in str(e).lower():
@@ -839,30 +821,42 @@ class VikingFS:
)
raise
- # Remove carried lock file from the copy (directory only)
- if is_dir:
- carried_lock = new_path.rstrip("/") + f"/{MULTIWRITE_PATH_LOCK_FILE}"
- try:
- await self._async_agfs.rm(carried_lock)
- except Exception:
- pass
-
# Update VectorDB URIs (on failure, clean up the copy)
try:
await self._update_vector_store_uris(uris_to_move, old_uri, new_uri, ctx=ctx)
except Exception:
try:
if is_dir:
- await self._async_agfs.rm(new_path, recursive=True)
+ cleanup_lease = await self._async_agfs.pathlock_acquire_tree(
+ new_path,
+ owner_lease_ref=lease,
+ )
+ try:
+ await self._async_agfs.rm(
+ new_path,
+ recursive=True,
+ fs_ctx=self._pathlock_fs_ctx(ctx, cleanup_lease),
+ )
+ finally:
+ await self._async_agfs.pathlock_release(cleanup_lease)
else:
- await self._async_agfs.rm(new_path)
+ await self._async_agfs.rm(
+ new_path,
+ fs_ctx=self._pathlock_fs_ctx(ctx, lease),
+ )
except Exception:
pass
raise
# Delete source
- await self._async_agfs.rm(old_path, recursive=is_dir)
+ await self._async_agfs.rm(
+ old_path,
+ recursive=is_dir,
+ fs_ctx=self._pathlock_fs_ctx(ctx, lease),
+ )
return {}
+ finally:
+ await self._async_agfs.pathlock_release(lease)
async def system_sync_status(
self, uri: str, ctx: Optional[RequestContext] = None
@@ -897,39 +891,91 @@ class VikingFS:
is_dir: bool,
is_temp: bool,
ctx: Optional[RequestContext] = None,
- lock_handle: Optional["LockHandle"] = None,
+ lease_ref: Dict[str, Any] | None = None,
) -> None:
"""Copy source to destination for mv without deleting source."""
if is_temp:
- await self._async_agfs.cp(
- old_path,
- new_path,
- recursive=is_dir,
- fs_ctx={"account_id": self._ctx_or_default(ctx).account_id},
- )
+ if is_dir:
+ await self._copy_temp_dir_with_exact_locks(
+ old_path,
+ new_path,
+ ctx=ctx,
+ lease_ref=lease_ref,
+ )
+ else:
+ await self._async_agfs.cp(
+ old_path,
+ new_path,
+ recursive=False,
+ fs_ctx=self._pathlock_fs_ctx(ctx, lease_ref),
+ )
return
if is_dir:
- await self._copy_dir_through_vikingfs(
- old_uri, new_uri, ctx=ctx, lock_handle=lock_handle
- )
+ await self._copy_dir_through_vikingfs(old_uri, new_uri, ctx=ctx, lease_ref=lease_ref)
else:
- await self._copy_file_through_vikingfs(
- old_uri,
- new_uri,
- ctx=ctx,
- lock_handle=lock_handle,
+ await self._copy_file_through_vikingfs(old_uri, new_uri, ctx=ctx, lease_ref=lease_ref)
+
+ async def _copy_temp_dir_with_exact_locks(
+ self,
+ old_path: str,
+ new_path: str,
+ ctx: Optional[RequestContext],
+ lease_ref: Dict[str, Any] | None,
+ ) -> None:
+ """Copy an encrypted temp directory while locking every destination entry.
+
+ Args:
+ old_path: Source backend directory path.
+ new_path: Destination backend directory path.
+ ctx: Request context used for filesystem operations.
+ lease_ref: Exact lease covering the current destination directory.
+
+ Returns:
+ None.
+ """
+ if lease_ref is None:
+ raise ValueError("temp directory copy requires a pathlock lease")
+ fs_ctx = self._pathlock_fs_ctx(ctx, lease_ref)
+ await self._async_agfs.mkdir(new_path, fs_ctx=fs_ctx)
+ entries = await self._async_agfs.ls(old_path, fs_ctx=fs_ctx)
+ for entry in entries:
+ name = entry.get("name", "")
+ if not name or name in (".", ".."):
+ continue
+ old_child = f"{old_path.rstrip('/')}/{name}"
+ new_child = f"{new_path.rstrip('/')}/{name}"
+ child_lease = await self._async_agfs.pathlock_acquire_exact(
+ new_child,
+ owner_lease_ref=lease_ref,
)
+ try:
+ if entry.get("isDir", False):
+ await self._copy_temp_dir_with_exact_locks(
+ old_child,
+ new_child,
+ ctx=ctx,
+ lease_ref=child_lease,
+ )
+ else:
+ await self._async_agfs.cp(
+ old_child,
+ new_child,
+ recursive=False,
+ fs_ctx=self._pathlock_fs_ctx(ctx, child_lease),
+ )
+ finally:
+ await self._async_agfs.pathlock_release(child_lease)
async def _copy_dir_through_vikingfs(
self,
old_uri: str,
new_uri: str,
ctx: Optional[RequestContext] = None,
- lock_handle: Optional["LockHandle"] = None,
+ lease_ref: Dict[str, Any] | None = None,
) -> None:
"""Recursively copy a directory through VikingFS read/write hooks."""
- await self.mkdir(new_uri, exist_ok=True, ctx=ctx)
+ await self.mkdir(new_uri, exist_ok=True, ctx=ctx, lease_ref=lease_ref)
entries = await self.ls(old_uri, show_all_hidden=True, ctx=ctx)
for entry in entries:
@@ -943,14 +989,14 @@ class VikingFS:
old_child_uri,
new_child_uri,
ctx=ctx,
- lock_handle=lock_handle,
+ lease_ref=lease_ref,
)
else:
await self._copy_file_through_vikingfs(
old_child_uri,
new_child_uri,
ctx=ctx,
- lock_handle=lock_handle,
+ lease_ref=lease_ref,
)
async def _copy_file_through_vikingfs(
@@ -958,11 +1004,23 @@ class VikingFS:
from_uri: str,
to_uri: str,
ctx: Optional[RequestContext] = None,
- lock_handle: Optional["LockHandle"] = None,
+ lease_ref: Dict[str, Any] | None = None,
) -> None:
"""Copy one file through VikingFS read/write hooks without deleting source."""
content_bytes = await self.read_file_bytes(from_uri, ctx=ctx)
- await self.write_file_bytes(to_uri, content_bytes, ctx=ctx, lock_handle=lock_handle)
+ if lease_ref is None:
+ await self.write_file_bytes(to_uri, content_bytes, ctx=ctx)
+ return
+
+ child_path = self._uri_to_path(to_uri, ctx=ctx)
+ child_lease = await self._async_agfs.pathlock_acquire_exact(
+ child_path,
+ owner_lease_ref=lease_ref,
+ )
+ try:
+ await self.write_file_bytes(to_uri, content_bytes, ctx=ctx, lease_ref=child_lease)
+ finally:
+ await self._async_agfs.pathlock_release(child_lease)
async def grep(
self,
@@ -1178,19 +1236,15 @@ class VikingFS:
if exclude_uri:
excluded_prefix = exclude_uri.rstrip("/")
self._ensure_access(excluded_prefix, ctx)
- filter_expr = And(
- [
- filter_expr,
- RawDSL(
- {
- "op": "must_not",
- "field": "uri",
- "conds": [excluded_prefix],
- "para": "-d=-1",
- }
- ),
- ]
- )
+ filter_expr = And([
+ filter_expr,
+ RawDSL({
+ "op": "must_not",
+ "field": "uri",
+ "conds": [excluded_prefix],
+ "para": "-d=-1",
+ }),
+ ])
# Auto-adapt bm25 recall limit: recall up to 5x requested matches
# while capping at VikingDB's max limit. If node_limit is unset,
@@ -1360,13 +1414,11 @@ class VikingFS:
files_scanned_set.add(file_uri)
- results.append(
- {
- "line": match.get("line", match.get("line_number", 0)),
- "uri": file_uri,
- "content": match.get("content", ""),
- }
- )
+ results.append({
+ "line": match.get("line", match.get("line_number", 0)),
+ "uri": file_uri,
+ "content": match.get("content", ""),
+ })
if node_limit and len(results) >= node_limit:
break
@@ -1536,13 +1588,11 @@ class VikingFS:
lines = content.split("\n")
for line_num, line in enumerate(lines, 1):
if compiled_pattern.search(line):
- matches.append(
- {
- "line": line_num,
- "uri": entry_uri,
- "content": line,
- }
- )
+ matches.append({
+ "line": line_num,
+ "uri": entry_uri,
+ "content": line,
+ })
return matches, 1
except Exception as e:
logger.debug(f"Failed to grep {entry_uri}: {e}")
@@ -1565,7 +1615,7 @@ class VikingFS:
Extra field:
isLocked (bool): Whether the path is currently held by a path lock
(either the path itself or any ancestor directory). Returns
- False when the LockManager is not initialized or the lookup
+ False when the pathlock system is not enabled or the lookup
fails.
count (int): For directories, the number of nodes in the vector index
under this directory (including subdirectories). For files, this
@@ -1628,11 +1678,9 @@ class VikingFS:
return result
async def _is_path_locked_async(self, path: str) -> bool:
- """Best-effort async path-lock lookup; returns False when LockManager is absent."""
+ """Best-effort async path-lock lookup; returns False on any error."""
try:
- from openviking.storage.transaction import get_lock_manager
-
- return await get_lock_manager().is_path_locked_async(path)
+ return await self._async_agfs.pathlock_is_locked(path)
except Exception:
return False
@@ -1827,17 +1875,15 @@ class VikingFS:
):
info = entry["info"]
new_entry = dict(entry.get("extra", {}))
- new_entry.update(
- {
- "name": info["name"],
- "size": info["size"],
- "mode": info["mode"],
- "modTime": info["modTime"],
- "isDir": info["isDir"],
- "rel_path": entry["rel_path"],
- "uri": entry_uri,
- }
- )
+ new_entry.update({
+ "name": info["name"],
+ "size": info["size"],
+ "mode": info["mode"],
+ "modTime": info["modTime"],
+ "isDir": info["isDir"],
+ "rel_path": entry["rel_path"],
+ "uri": entry_uri,
+ })
result.append(new_entry)
return result
@@ -1862,15 +1908,13 @@ class VikingFS:
):
info = entry["info"]
is_dir = info["isDir"]
- result.append(
- {
- "uri": entry_uri,
- "size": 0 if is_dir else info["size"],
- "isDir": is_dir,
- "modTime": format_iso8601(parse_iso_datetime(info["modTime"])),
- "rel_path": entry["rel_path"],
- }
- )
+ result.append({
+ "uri": entry_uri,
+ "size": 0 if is_dir else info["size"],
+ "isDir": is_dir,
+ "modTime": format_iso8601(parse_iso_datetime(info["modTime"])),
+ "rel_path": entry["rel_path"],
+ })
await self._batch_fetch_abstracts(result, abs_limit, ctx=ctx)
@@ -3049,17 +3093,28 @@ class VikingFS:
# ========== Parent Directory Creation ==========
- async def _ensure_parent_dirs(self, path: str, ctx: Optional[RequestContext] = None) -> None:
+ async def _ensure_parent_dirs(
+ self,
+ path: str,
+ ctx: Optional[RequestContext] = None,
+ lease_ref: Dict[str, Any] | None = None,
+ ) -> None:
"""Recursively create all parent directories."""
try:
- await self._async_agfs.ensure_parent_dirs(path)
+ await self._async_agfs.ensure_parent_dirs(
+ path,
+ fs_ctx=self._pathlock_fs_ctx(ctx, lease_ref),
+ )
except Exception as e:
logger.debug(f"Failed to ensure parent directories for {path}: {e}")
parent = path.rstrip("/").rsplit("/", 1)[0]
- await self._mkdir_path_with_parents(parent, ctx=ctx)
+ await self._mkdir_path_with_parents(parent, ctx=ctx, lease_ref=lease_ref)
async def _mkdir_path_with_parents(
- self, dir_path: str, ctx: Optional[RequestContext] = None
+ self,
+ dir_path: str,
+ ctx: Optional[RequestContext] = None,
+ lease_ref: Dict[str, Any] | None = None,
) -> None:
"""Create a directory path segment-by-segment using the same fs context."""
parts = [part for part in dir_path.strip("/").split("/") if part]
@@ -3067,7 +3122,10 @@ class VikingFS:
for part in parts:
current = f"{current}/{part}"
try:
- await self._async_agfs.mkdir(current)
+ await self._async_agfs.mkdir(
+ current,
+ fs_ctx=self._pathlock_fs_ctx(ctx, lease_ref),
+ )
except Exception as e:
message = str(e).lower()
if "exist" in message or "already" in message:
@@ -3144,21 +3202,17 @@ class VikingFS:
uri: str,
content: Union[str, bytes],
ctx: Optional[RequestContext] = None,
- lock_handle: Optional["LockHandle"] = None,
+ lease_ref: Dict[str, Any] | None = None,
) -> None:
- """Write file directly."""
+ """Write file directly. Encryption lock handled internally by EncryptionWrappedFS."""
self._ensure_mutable_access(uri, ctx)
path = self._uri_to_path(uri, ctx=ctx)
- await self._ensure_parent_dirs(path, ctx=ctx)
+ await self._ensure_parent_dirs(path, ctx=ctx, lease_ref=lease_ref)
if isinstance(content, str):
content = content.encode("utf-8")
- await self._run_with_encrypted_write_lock(
- path,
- lambda: self._async_agfs.write(path, content),
- lock_handle=lock_handle,
- )
+ await self._async_agfs.write(path, content, fs_ctx=self._pathlock_fs_ctx(ctx, lease_ref))
async def read_file(
self,
@@ -3259,59 +3313,63 @@ class VikingFS:
uri: str,
content: bytes,
ctx: Optional[RequestContext] = None,
- lock_handle: Optional["LockHandle"] = None,
+ lease_ref: Dict[str, Any] | None = None,
) -> None:
- """Write single binary file."""
+ """Write single binary file. Encryption lock handled internally by EncryptionWrappedFS."""
self._ensure_mutable_access(uri, ctx)
path = self._uri_to_path(uri, ctx=ctx)
- await self._ensure_parent_dirs(path, ctx=ctx)
+ await self._ensure_parent_dirs(path, ctx=ctx, lease_ref=lease_ref)
- await self._run_with_encrypted_write_lock(
- path,
- lambda: self._async_agfs.write(path, content),
- lock_handle=lock_handle,
- )
+ await self._async_agfs.write(path, content, fs_ctx=self._pathlock_fs_ctx(ctx, lease_ref))
async def append_file(
self,
uri: str,
content: str,
ctx: Optional[RequestContext] = None,
- lock_handle: Optional["LockHandle"] = None,
+ lease_ref: Dict[str, Any] | None = None,
) -> None:
- """Append content to file."""
+ """Append content to file while holding one exact pathlock lease."""
self._ensure_mutable_access(uri, ctx)
path = self._uri_to_path(uri, ctx=ctx)
+ owned_lease = None
try:
- await self._ensure_parent_dirs(path, ctx=ctx)
-
- async def _append_under_lock() -> None:
- """Read old content and rewrite the whole file under lock to avoid lost updates."""
- existing = ""
- try:
- existing_bytes = self._handle_agfs_read(await self._async_agfs.read(path))
- existing = self._decode_bytes(existing_bytes)
- except FileNotFoundError:
- pass
- except AGFSHTTPError as e:
- if e.status_code != 404:
- raise
- except AGFSClientError:
+ await self._ensure_parent_dirs(path, ctx=ctx, lease_ref=lease_ref)
+ lease = lease_ref
+ if lease is None:
+ lease = await self._async_agfs.pathlock_acquire_exact(path)
+ owned_lease = lease
+ fs_ctx = self._pathlock_fs_ctx(ctx, lease)
+
+ # Read old content and rewrite the whole file to avoid lost updates.
+ existing = ""
+ try:
+ existing_bytes = self._handle_agfs_read(
+ await self._async_agfs.read(path, fs_ctx=fs_ctx)
+ )
+ existing = self._decode_bytes(existing_bytes)
+ except FileNotFoundError:
+ pass
+ except AGFSHTTPError as e:
+ if e.status_code != 404:
raise
+ except AGFSClientError:
+ raise
- final_content = (existing + content).encode("utf-8")
- await self._async_agfs.write(path, final_content)
-
- await self._run_with_encrypted_write_lock(
+ final_content = (existing + content).encode("utf-8")
+ await self._async_agfs.write(
path,
- _append_under_lock,
- lock_handle=lock_handle,
+ final_content,
+ fs_ctx=fs_ctx,
)
except Exception as e:
logger.error(f"[VikingFS] Failed to append to file {uri}: {e}")
raise IOError(f"Failed to append to file {uri}: {e}")
+ finally:
+ if owned_lease is not None:
+ await self._async_agfs.pathlock_release(owned_lease)
async def ls(
self,
@@ -3544,24 +3602,32 @@ class VikingFS:
temp_uri: str,
target_uri: str,
ctx: Optional[RequestContext] = None,
+ lease_ref: Dict[str, Any] | None = None,
) -> None:
"""Persist an already-encrypted temp tree without rewriting file bytes."""
self._ensure_access(temp_uri, ctx)
self._ensure_mutable_access(target_uri, ctx)
src_path = self._uri_to_path(temp_uri, ctx=ctx)
dst_path = self._uri_to_path(target_uri, ctx=ctx)
- await self._ensure_parent_dirs(dst_path, ctx=ctx)
+ fs_ctx = self._pathlock_fs_ctx(ctx, lease_ref)
+ await self._ensure_parent_dirs(dst_path, ctx=ctx, lease_ref=lease_ref)
await self._async_agfs.cp(
src_path,
dst_path,
recursive=True,
- fs_ctx={"account_id": self._ctx_or_default(ctx).account_id},
+ fs_ctx=fs_ctx or {"account_id": self._ctx_or_default(ctx).account_id},
)
- async def delete_temp(self, temp_uri: str, ctx: Optional[RequestContext] = None) -> None:
+ async def delete_temp(
+ self,
+ temp_uri: str,
+ ctx: Optional[RequestContext] = None,
+ lease_ref: Dict[str, Any] | None = None,
+ ) -> None:
"""Delete temp directory and its contents."""
self._ensure_mutable_access(temp_uri, ctx)
path = self._uri_to_path(temp_uri, ctx=ctx)
+ fs_ctx = self._pathlock_fs_ctx(ctx, lease_ref)
try:
for entry in await self._ls_entries(path, ctx=ctx):
name = entry.get("name", "")
@@ -3569,10 +3635,10 @@ class VikingFS:
continue
entry_path = f"{path}/{name}"
if entry.get("isDir"):
- await self.delete_temp(f"{temp_uri}/{name}", ctx=ctx)
+ await self.delete_temp(f"{temp_uri}/{name}", ctx=ctx, lease_ref=lease_ref)
else:
- await self._async_agfs.rm(entry_path)
- await self._async_agfs.rm(path)
+ await self._async_agfs.rm(entry_path, fs_ctx=fs_ctx)
+ await self._async_agfs.rm(path, fs_ctx=fs_ctx)
except Exception as e:
logger.warning(f"[VikingFS] Failed to delete temp {temp_uri}: {e}")
@@ -3665,16 +3731,14 @@ class VikingFS:
# crates/ragfs/src/git/enumerate.rs and VikingFS._INTERNAL_NAMES so that
# callers fail fast in Python with a clear error rather than passing a
# path that the Rust side will silently drop.
- _GIT_INTERNAL_FIRST_SEGMENTS = frozenset(
- {
- "_system",
- "tasks",
- "temp",
- "queue",
- "upload",
- ".path.ovlock",
- }
- )
+ _GIT_INTERNAL_FIRST_SEGMENTS = frozenset({
+ "_system",
+ "tasks",
+ "temp",
+ "queue",
+ "upload",
+ ".path.ovlock",
+ })
_DEFAULT_GIT_AUTHOR_NAME = "viking-bot"
_DEFAULT_GIT_AUTHOR_EMAIL = "[email protected]"
@@ -3951,7 +4015,6 @@ class VikingFS:
from openviking.pyagfs.exceptions import GitRestoreWritebackPartialError
from openviking.storage.errors import LockAcquisitionError, ResourceBusyError
- from openviking.storage.transaction import LockContext, get_lock_manager
# Serialize the writeback against concurrent VFS mutations on the same
# subtree. A scoped restore tree-locks project_dir; a full restore
@@ -3966,21 +4029,25 @@ class VikingFS:
)
partial_exc: Optional[GitRestoreWritebackPartialError] = None
try:
- async with LockContext(get_lock_manager(), [lock_path], lock_mode="tree"):
- try:
- result = await self._async_agfs.run("git_restore", **kwargs)
- except GitRestoreWritebackPartialError as exc:
- # The ref already advanced — capture the exception and
- # finish the lock scope cleanly. Reindex scheduling and
- # re-raise happen below, outside the tree lock.
- partial_exc = exc
- result = None
+ lease = await self._async_agfs.pathlock_acquire_tree(lock_path)
except LockAcquisitionError:
raise ResourceBusyError(
f"Resource is being processed: {project_dir or '*'}",
uri=project_dir or "*",
)
+ try:
+ try:
+ result = await self._async_agfs.run("git_restore", **kwargs)
+ except GitRestoreWritebackPartialError as exc:
+ # The ref already advanced — capture the exception and
+ # finish the lock scope cleanly. Reindex scheduling and
+ # re-raise happen below, outside the tree lock.
+ partial_exc = exc
+ result = None
+ finally:
+ await self._async_agfs.pathlock_release(lease)
+
if partial_exc is not None:
# HEAD has moved forward but some VFS writes/deletes failed.
# Still schedule reindex for the paths that *did* reach the VFS so
@@ -4339,12 +4406,10 @@ class VikingFS:
from openviking.service.reindex_executor import get_reindex_executor
executor = get_reindex_executor()
- await asyncio.gather(
- *[
- self._run_vector_rebuild(executor, op, uri, level, ctx)
- for (op, uri, level) in tasks
- ]
- )
+ await asyncio.gather(*[
+ self._run_vector_rebuild(executor, op, uri, level, ctx)
+ for (op, uri, level) in tasks
+ ])
await tracker.complete(
task_id,
{"status": "completed", "task_count": len(tasks)},
diff --git a/openviking/utils/agfs_utils.py b/openviking/utils/agfs_utils.py
index 0495f8961..7e36d243c 100644
--- a/openviking/utils/agfs_utils.py
+++ b/openviking/utils/agfs_utils.py
@@ -35,6 +35,7 @@ class RagfsBindingConfig:
"""Convert the runtime config into the sectioned dict consumed by `RAGFSBindingClient`."""
binding_config: Dict[str, Any] = {
"cache": self.agfs.cache.model_dump(mode="json"),
+ "pathlock": self.agfs.pathlock.model_dump(mode="json"),
}
if self.root_key is not None:
diff --git a/openviking/utils/resource_processor.py b/openviking/utils/resource_processor.py
index 553e42be7..3e3ccaba4 100644
--- a/openviking/utils/resource_processor.py
+++ b/openviking/utils/resource_processor.py
@@ -28,12 +28,6 @@ from openviking.storage import VikingDBManager
from openviking.storage.errors import LockAcquisitionError
from openviking.storage.expr import And, Eq, PathScope
from openviking.storage.internal_names import STORAGE_INTERNAL_ENTRY_NAMES
-from openviking.storage.transaction import (
- LOCK_TIMEOUT_DEFAULT,
- NO_LOCK,
- LockLease,
- OwnedLockLease,
-)
from openviking.storage.queuefs.semantic_processor import SemanticProcessor
from openviking.storage.viking_fs import LS_ALL_NODES, get_viking_fs
from openviking.telemetry import get_current_telemetry
@@ -188,7 +182,7 @@ class ResourceProcessor:
"source_path": None,
}
defer_post_processing = bool(kwargs.pop("defer_post_processing", False))
- preacquired_lock = kwargs.pop("resource_lock", NO_LOCK) or NO_LOCK
+ preacquired_lock = kwargs.pop("resource_lock", None)
ingest_options = IngestOptions.from_value(kwargs.pop("ingest_options", None))
telemetry = get_current_telemetry()
@@ -331,20 +325,17 @@ class ResourceProcessor:
temp_uri = result.get("temp_uri") # temp_doc_uri
original_temp_uri = temp_uri # 保存原始 temp_uri 用于最终输出
candidate_uri = getattr(context_tree, "_candidate_uri", None) if context_tree else None
- resource_lock: LockLease = preacquired_lock
+ resource_lock: Optional[Dict[str, Any]] = preacquired_lock
target_preexisting = False
source_committed = False
if root_uri and temp_uri:
- from openviking.storage.transaction import get_lock_manager
-
stage_start = time.perf_counter()
stage_status = "ok"
viking_fs = get_viking_fs()
- lock_manager = get_lock_manager()
try:
if candidate_uri:
- if resource_lock.active:
+ if resource_lock is not None:
root_uri = candidate_uri
else:
root_uri, resource_lock = await self.reserve_unique_candidate(
@@ -379,17 +370,21 @@ class ResourceProcessor:
target_preexisting = False
except Exception:
pass
- if not resource_lock.active:
+ if resource_lock is None:
dst_path = viking_fs._uri_to_path(root_uri, ctx=ctx)
- resource_lock = await self.acquire_resource_lock(
- lock_manager, dst_path, uri=root_uri
- )
+ resource_lock = await self.acquire_resource_lock(dst_path, uri=root_uri)
if not target_preexisting:
- await viking_fs.persist_temp_tree(temp_uri, root_uri, ctx=ctx)
- await rewrite_image_uris(
- root_uri, ctx=ctx, lock_handle=resource_lock.handle
+ await viking_fs.persist_temp_tree(
+ temp_uri,
+ root_uri,
+ ctx=ctx,
+ lease_ref=resource_lock,
+ )
+ await rewrite_image_uris(root_uri, ctx=ctx, lease_ref=resource_lock)
+ await viking_fs.delete_temp(
+ parse_result.temp_dir_path,
+ ctx=ctx,
)
- await viking_fs.delete_temp(parse_result.temp_dir_path, ctx=ctx)
temp_uri = root_uri
source_committed = True
except Exception:
@@ -449,7 +444,7 @@ class ResourceProcessor:
prepared: Dict[str, Any],
*,
ctx: RequestContext,
- resource_lock: LockLease = NO_LOCK,
+ resource_lock: Optional[Dict[str, Any]] = None,
summarize: bool = False,
processing_mode: ProcessingMode = DEFAULT_PROCESSING_MODE,
**kwargs: Any,
@@ -486,12 +481,12 @@ class ResourceProcessor:
**kwargs,
)
if (
- resource_lock.active
+ resource_lock is not None
and summary_result.get("status") == "success"
and summary_result.get("enqueued_count", 0) > 0
):
- await resource_lock.handoff()
- resource_lock = NO_LOCK
+ await get_viking_fs()._async_agfs.pathlock_handoff(resource_lock)
+ resource_lock = None
except Exception as exc:
logger.error("Summarization failed: %s", exc)
result["warnings"] = [f"Summarization failed: {exc}"]
@@ -507,7 +502,7 @@ class ResourceProcessor:
except Exception:
pass
- if resource_lock.active:
+ if resource_lock is not None:
try:
sync_deleted_files: list[str] = []
sync_deleted_dirs: list[str] = []
@@ -523,11 +518,16 @@ class ResourceProcessor:
sync_deleted_files = list(getattr(diff, "deleted_files", []))
sync_deleted_dirs = list(getattr(diff, "deleted_dirs", []))
else:
- await viking_fs.persist_temp_tree(temp_uri, root_uri, ctx=ctx)
+ await viking_fs.persist_temp_tree(
+ temp_uri,
+ root_uri,
+ ctx=ctx,
+ lease_ref=resource_lock,
+ )
await rewrite_image_uris(
root_uri,
ctx=ctx,
- lock_handle=resource_lock.handle,
+ lease_ref=resource_lock,
)
if temp_dir_path:
await viking_fs.delete_temp(temp_dir_path, ctx=ctx)
@@ -545,7 +545,7 @@ class ResourceProcessor:
ingest_options=ingest_options,
)
finally:
- await resource_lock.close()
+ await get_viking_fs()._async_agfs.pathlock_release(resource_lock)
elif vectors_only:
if not build_index:
return result
@@ -575,13 +575,11 @@ class ResourceProcessor:
await self.vikingdb.delete(ids, ctx=ctx)
for uri in dict.fromkeys(dirs):
records = await self.vikingdb.filter(
- filter=And(
- [
- PathScope("uri", uri, depth=-1),
- Eq("level", int(ContextLevel.DETAIL)),
- Eq("account_id", ctx.account_id),
- ]
- ),
+ filter=And([
+ PathScope("uri", uri, depth=-1),
+ Eq("level", int(ContextLevel.DETAIL)),
+ Eq("account_id", ctx.account_id),
+ ]),
limit=VECTORDB_MAX_QUERY_LIMIT,
output_fields=["id"],
ctx=ctx,
@@ -631,13 +629,11 @@ class ResourceProcessor:
candidate_uri: str,
ctx: RequestContext,
max_attempts: int = 100,
- ) -> tuple[str, OwnedLockLease]:
+ ) -> tuple[str, Dict[str, Any]]:
"""Pick the first free candidate URI and reserve it with a resource TreeLock."""
from openviking.storage.errors import ResourceBusyError
- from openviking.storage.transaction import get_lock_manager
viking_fs = get_viking_fs()
- lock_manager = get_lock_manager()
last_busy_error: Optional[ResourceBusyError] = None
for attempt in range(max_attempts + 1):
@@ -648,7 +644,7 @@ class ResourceProcessor:
dst_path = viking_fs._uri_to_path(root_uri, ctx=ctx)
try:
resource_lock = await self.acquire_resource_lock(
- lock_manager, dst_path, uri=root_uri, timeout=0.0
+ dst_path, uri=root_uri, timeout=0.0
)
return root_uri, resource_lock
except ResourceBusyError as exc:
@@ -670,17 +666,18 @@ class ResourceProcessor:
@staticmethod
async def acquire_resource_lock(
- lock_manager,
path: str,
*,
uri: str = "",
- timeout: Any = LOCK_TIMEOUT_DEFAULT,
- ) -> OwnedLockLease:
+ timeout: float = 0.0,
+ ) -> Dict[str, Any]:
"""Acquire the per-resource TreeLock or raise a structured conflict."""
from openviking.storage.errors import ResourceBusyError
try:
- return await OwnedLockLease.acquire_tree(lock_manager, path, timeout=timeout)
+ return await get_viking_fs()._async_agfs.pathlock_acquire_tree(
+ path, timeout_secs=timeout
+ )
except LockAcquisitionError as exc:
logger.warning(f"[ResourceProcessor] Failed to acquire resource lock on {path}")
raise ResourceBusyError(
diff --git a/openviking/utils/summarizer.py b/openviking/utils/summarizer.py
index 83f42092e..d7e519471 100644
--- a/openviking/utils/summarizer.py
+++ b/openviking/utils/summarizer.py
@@ -10,7 +10,6 @@ from typing import TYPE_CHECKING, Any, Dict, List, Optional, Tuple
from openviking.utils.ingest_options import IngestOptions
from openviking.core.namespace import context_type_for_uri
from openviking.storage.queuefs import SemanticMsg, get_queue_manager
-from openviking.storage.transaction import NO_LOCK, LockLease
from openviking.storage.viking_fs import LS_ALL_NODES, get_viking_fs
from openviking.telemetry import get_current_telemetry
from openviking.telemetry.request_wait_tracker import get_request_wait_tracker
@@ -37,7 +36,7 @@ class Summarizer:
resource_uris: List[str],
ctx: "RequestContext",
skip_vectorization: bool = False,
- lock: LockLease = NO_LOCK,
+ lock: Optional[Dict[str, Any]] = None,
**kwargs,
) -> Dict[str, Any]:
"""
@@ -62,7 +61,9 @@ class Summarizer:
enqueued_count = 0
telemetry = get_current_telemetry()
- lock_handoff = lock.to_handoff()
+ lock_handoff: Optional[Dict[str, Any]] = None
+ if lock is not None:
+ lock_handoff = await get_viking_fs()._async_agfs.pathlock_to_handoff(lock)
target_preexisting_arg = kwargs.get("target_preexisting")
def resolve_target_preexisting(index: int, target_uri: str) -> Optional[bool]:
diff --git a/openviking_cli/utils/config/agfs_config.py b/openviking_cli/utils/config/agfs_config.py
index 3f6a5b190..feed25756 100644
--- a/openviking_cli/utils/config/agfs_config.py
+++ b/openviking_cli/utils/config/agfs_config.py
@@ -315,6 +315,30 @@ class AGFSCacheConfig(BaseModel):
return self
+class AGFSPathLockConfig(BaseModel):
+ """Configuration for the native RAGFS path lock service."""
+
+ provider: str = Field(
+ default="filesystem",
+ description="PathLock provider: 'filesystem' | 'memory'",
+ )
+ lock_expire_secs: float = Field(
+ default=300.0,
+ description="Seconds before an unrefreshed lock token becomes stale.",
+ )
+
+ model_config = {"extra": "forbid"}
+
+ @model_validator(mode="after")
+ def validate_config(self):
+ """Validate provider and stale-lock expiry."""
+ if self.provider not in {"filesystem", "memory"}:
+ raise ValueError("pathlock provider must be one of: 'filesystem', 'memory'")
+ if self.lock_expire_secs < 1.0:
+ raise ValueError("pathlock lock_expire_secs must be >= 1.0")
+ return self
+
+
class AGFSConfig(BaseModel):
"""Configuration for RAGFS (Rust-based AGFS)."""
@@ -381,6 +405,11 @@ class AGFSConfig(BaseModel):
description="RAGFS cache configuration.",
)
+ pathlock: AGFSPathLockConfig = Field(
+ default_factory=AGFSPathLockConfig,
+ description="Native RAGFS path lock configuration.",
+ )
+
retry_times: Any = Field(
default=None,
exclude=True,
diff --git a/tests/agfs/test_async_client.py b/tests/agfs/test_async_client.py
index efcce6889..b5aa084e4 100644
--- a/tests/agfs/test_async_client.py
+++ b/tests/agfs/test_async_client.py
@@ -8,15 +8,24 @@ from openviking.pyagfs import AsyncAGFSClient
class _SyncAGFS:
+ """Minimal synchronous binding stub used by the async adapter tests."""
+
def read(self, path, **kwargs):
+ """Return read call arguments."""
return ("read", path, kwargs)
def write(self, path, data, **kwargs):
+ """Return write call arguments."""
return ("write", path, data, kwargs)
def rm(self, path, **kwargs):
+ """Return remove call arguments."""
return ("rm", path, kwargs)
+ def pathlock_is_locked(self, ctx, path, ignore_stale):
+ """Return pathlock query arguments."""
+ return ("pathlock_is_locked", ctx, path, ignore_stale)
+
@pytest.mark.asyncio
async def test_async_agfs_client_hides_threadpool(monkeypatch):
diff --git a/tests/agfs/test_fs_binding.py b/tests/agfs/test_fs_binding.py
index 0f6c913c3..ef074e043 100644
--- a/tests/agfs/test_fs_binding.py
+++ b/tests/agfs/test_fs_binding.py
@@ -13,7 +13,6 @@ import uuid
import pytest
-from openviking.storage.transaction import init_lock_manager, reset_lock_manager
from openviking.storage.viking_fs import init_viking_fs
from openviking_cli.utils.config.agfs_config import AGFSConfig
@@ -33,16 +32,12 @@ async def viking_fs_binding_instance():
# Create AGFS client
agfs_client = create_agfs_client(RagfsBindingConfig(agfs=AGFS_CONF))
- # Initialize LockManager and VikingFS with client
- init_lock_manager(agfs=agfs_client)
vfs = init_viking_fs(agfs=agfs_client)
# make sure default/temp directory exists
await vfs.mkdir("viking://temp/", exist_ok=True)
yield vfs
- reset_lock_manager()
-
@pytest.mark.asyncio
class TestVikingFSBindingLocal:
@@ -96,6 +91,78 @@ class TestVikingFSBindingLocal:
root_entries = await vfs.ls("viking://temp/")
assert not any(e["name"] == test_dir for e in root_entries)
+ async def test_borrowed_pathlock_cannot_release_via_raw_ref(self, viking_fs_binding_instance):
+ """Reject borrowed lifecycle control through typed and raw lease refs."""
+ vfs = viking_fs_binding_instance
+ path = f"/local/default/temp/borrowed_release_{uuid.uuid4().hex}.txt"
+ owned = await vfs._async_agfs.pathlock_acquire_exact(path)
+ borrowed = await vfs._async_agfs.pathlock_as_borrowed(owned)
+
+ try:
+ with pytest.raises(ValueError):
+ await vfs._async_agfs.pathlock_release(borrowed)
+ with pytest.raises((TypeError, ValueError)):
+ await vfs._async_agfs.pathlock_release(borrowed["lease_ref"])
+ finally:
+ await vfs._async_agfs.pathlock_release(owned)
+
+ async def test_pathlock_adopt_rejects_forged_tree_coverage(self, viking_fs_binding_instance):
+ """Reject handoff coverage that is stronger than the live token."""
+ vfs = viking_fs_binding_instance
+ path = f"/local/default/temp/handoff_forge_{uuid.uuid4().hex}.txt"
+ owned = await vfs._async_agfs.pathlock_acquire_exact(path)
+ handoff = await vfs._async_agfs.pathlock_to_handoff(owned)
+ handoff["covered_paths"] = [{"path": path, "kind": "tree"}]
+ adopted = None
+
+ try:
+ with pytest.raises(ValueError):
+ adopted = await vfs._async_agfs.pathlock_adopt(handoff)
+ finally:
+ if adopted is not None:
+ await vfs._async_agfs.pathlock_release(adopted)
+ await vfs._async_agfs.pathlock_release(owned)
+
+ async def test_pathlock_adopt_accepts_legacy_handle_id_handoff(
+ self, viking_fs_binding_instance
+ ):
+ """Accept legacy durable handoffs that use handle_id instead of owner_id."""
+ vfs = viking_fs_binding_instance
+ path = f"/local/default/temp/handoff_legacy_{uuid.uuid4().hex}.txt"
+ owned = await vfs._async_agfs.pathlock_acquire_exact(path)
+ handoff = await vfs._async_agfs.pathlock_to_handoff(owned)
+ legacy_handoff = {
+ "handle_id": handoff["owner_id"],
+ "lock_paths": handoff["lock_paths"],
+ }
+ adopted = None
+
+ try:
+ adopted = await vfs._async_agfs.pathlock_adopt(legacy_handoff)
+ assert adopted["owner_id"] == owned["owner_id"]
+ assert adopted["owned"] is True
+ finally:
+ if adopted is not None:
+ await vfs._async_agfs.pathlock_release(adopted)
+ await vfs._async_agfs.pathlock_release(owned)
+
+ @pytest.mark.parametrize(
+ "requests",
+ [
+ [],
+ [{"kind": "exact"}],
+ [{"path": "", "kind": "exact"}],
+ [{"path": "relative", "kind": "tree"}],
+ [{"path": "/local/default/temp/file", "kind": "other"}],
+ ],
+ )
+ async def test_pathlock_batch_rejects_invalid_requests(
+ self, viking_fs_binding_instance, requests
+ ):
+ """Reject malformed pathlock requests without applying defaults."""
+ with pytest.raises(ValueError):
+ await viking_fs_binding_instance._async_agfs.pathlock_acquire_batch(requests)
+
async def test_tree_operations(self, viking_fs_binding_instance):
"""Test VikingFS tree operations."""
vfs = viking_fs_binding_instance
diff --git a/tests/agfs/test_fs_binding_s3.py b/tests/agfs/test_fs_binding_s3.py
index 0e0020bc0..af545efdf 100644
--- a/tests/agfs/test_fs_binding_s3.py
+++ b/tests/agfs/test_fs_binding_s3.py
@@ -13,7 +13,6 @@ from pathlib import Path
import pytest
-from openviking.storage.transaction import init_lock_manager, reset_lock_manager
from openviking.storage.viking_fs import init_viking_fs
from openviking_cli.utils.config import OPENVIKING_CONFIG_ENV
from openviking_cli.utils.config.agfs_config import AGFSConfig
@@ -59,14 +58,10 @@ async def viking_fs_binding_s3_instance():
# Create AGFS client
agfs_client = create_agfs_client(RagfsBindingConfig(agfs=AGFS_CONF))
- # Initialize LockManager and VikingFS with client
- init_lock_manager(agfs=agfs_client)
vfs = init_viking_fs(agfs=agfs_client)
yield vfs
- reset_lock_manager()
-
@pytest.mark.asyncio
class TestVikingFSBindingS3:
diff --git a/tests/agfs/test_viking_fs_git.py b/tests/agfs/test_viking_fs_git.py
index c7609c00b..f1b489d92 100644
--- a/tests/agfs/test_viking_fs_git.py
+++ b/tests/agfs/test_viking_fs_git.py
@@ -80,21 +80,16 @@ def workspace():
@pytest.fixture
def vfs(workspace):
- from openviking.storage.transaction import init_lock_manager, reset_lock_manager
-
cfg, fs_root = _write_workspace(workspace)
client = _build_client(cfg, fs_root)
- init_lock_manager(client)
try:
yield VikingFS(agfs=client)
finally:
- reset_lock_manager()
+ pass
@pytest.fixture
def vfs_disabled(workspace):
- from openviking.storage.transaction import init_lock_manager, reset_lock_manager
-
cfg = workspace / "ragfs.toml"
cfg.write_text(
"""
@@ -106,11 +101,10 @@ enabled = false
fs_root.mkdir()
client = ragfs_python.RAGFSBindingClient(git_config_path=str(cfg))
client.mount("localfs", "/local", {"local_dir": str(fs_root)})
- init_lock_manager(client)
try:
yield VikingFS(agfs=client)
finally:
- reset_lock_manager()
+ pass
# =========================================================================
@@ -459,15 +453,12 @@ def encryptor(workspace):
@pytest.fixture
def vfs_encrypted(workspace, encryptor):
- from openviking.storage.transaction import init_lock_manager, reset_lock_manager
-
cfg, fs_root = _write_workspace(workspace)
client = _build_client(cfg, fs_root)
- init_lock_manager(client)
try:
yield VikingFS(agfs=client, encryptor=encryptor)
finally:
- reset_lock_manager()
+ pass
@pytest.mark.asyncio
diff --git a/tests/client/test_file_operations.py b/tests/client/test_file_operations.py
index 2df2a910c..6d2edb64c 100644
--- a/tests/client/test_file_operations.py
+++ b/tests/client/test_file_operations.py
@@ -8,7 +8,6 @@ from pathlib import Path
import pytest
from openviking import AsyncOpenViking
-from openviking.storage.transaction import release_all_locks
class TestRm:
@@ -23,7 +22,6 @@ class TestRm:
reason="Test rm",
)
- await release_all_locks()
uris = await client.tree(result["root_uri"])
for data in uris:
if not data["isDir"]:
@@ -37,8 +35,6 @@ class TestRm:
for f in sample_directory.glob("**/*.txt"):
await client.add_resource(path=str(f), reason="Test rm dir")
- # Release resource locks held by add_resource before rm
- await release_all_locks()
entries = await client.ls("viking://resources/")
for data in entries:
if data["isDir"]:
@@ -60,7 +56,6 @@ class TestMv:
)
uri = result["root_uri"]
new_uri = "viking://resources/moved/"
- await release_all_locks()
await client.mv(uri, new_uri)
# Verify original location does not exist
with pytest.raises(Exception): # noqa: B017
diff --git a/tests/client/test_git_versioning.py b/tests/client/test_git_versioning.py
index 4fc8e43c3..4a8ba850e 100644
--- a/tests/client/test_git_versioning.py
+++ b/tests/client/test_git_versioning.py
@@ -15,18 +15,18 @@ from unittest.mock import MagicMock
import pytest
-ragfs_python = pytest.importorskip("ragfs_python")
-
from openviking.async_client import AsyncOpenViking
from openviking.client.local import LocalClient
from openviking.pyagfs.exceptions import AGFSNotFoundError, AGFSNotSupportedError
from openviking.server.identity import RequestContext, Role
-from openviking_cli.exceptions import InvalidURIError
from openviking.service.fs_service import FSService
from openviking.storage.viking_fs import VikingFS
from openviking.sync_client import SyncOpenViking
+from openviking_cli.exceptions import InvalidURIError
from openviking_cli.session.user_id import UserIdentifier
+ragfs_python = pytest.importorskip("ragfs_python")
+
OID_RE = re.compile(r"^[0-9a-f]{40}$")
DEFAULT_AUTHOR_NAME = VikingFS._DEFAULT_GIT_AUTHOR_NAME
@@ -86,11 +86,8 @@ def _build_binding_client(config_path: Path, fs_root: Path):
def _build_harness(config_path: Path, fs_root: Path) -> ClientHarness:
- from openviking.storage.transaction import init_lock_manager
-
ctx = _make_ctx()
binding_client = _build_binding_client(config_path, fs_root)
- init_lock_manager(binding_client)
vfs = VikingFS(agfs=binding_client)
fs_service = FSService()
@@ -131,24 +128,20 @@ def workspace():
@pytest.fixture
def git_harness(workspace) -> ClientHarness:
- from openviking.storage.transaction import reset_lock_manager
-
cfg, fs_root = _write_workspace(workspace)
try:
yield _build_harness(cfg, fs_root)
finally:
- reset_lock_manager()
+ pass
@pytest.fixture
def git_disabled_harness(workspace) -> ClientHarness:
- from openviking.storage.transaction import reset_lock_manager
-
cfg, fs_root = _write_disabled_workspace(workspace)
try:
yield _build_harness(cfg, fs_root)
finally:
- reset_lock_manager()
+ pass
async def test_write_commit_show_roundtrip(git_harness):
@@ -165,10 +158,13 @@ async def test_write_commit_show_roundtrip(git_harness):
assert commit["result"] == "created"
assert OID_RE.match(commit["commit_oid"])
- assert git_harness.client.snapshot.show(
- "main",
- path="viking://resources/a.md",
- ) == b"hello"
+ assert (
+ git_harness.client.snapshot.show(
+ "main",
+ path="viking://resources/a.md",
+ )
+ == b"hello"
+ )
async def test_show_metadata_without_path(git_harness):
@@ -284,10 +280,13 @@ async def test_restore_reverts_file_and_advances_head(git_harness):
assert restore["source_commit"] == v1["commit_oid"]
assert restore["parent_commit"] == v2["commit_oid"]
assert restore["new_commit_oid"] != v2["commit_oid"]
- assert await git_harness.vfs.read(
- "viking://resources/proj/a.md",
- ctx=git_harness.ctx,
- ) == b"v1"
+ assert (
+ await git_harness.vfs.read(
+ "viking://resources/proj/a.md",
+ ctx=git_harness.ctx,
+ )
+ == b"v1"
+ )
assert git_harness.client.snapshot.show("main")["parents"] == [v2["commit_oid"]]
@@ -320,10 +319,13 @@ async def test_restore_dry_run_does_not_mutate(git_harness):
assert dry_run["result"] == "dry_run"
assert any(item["path"] == "a.md" for item in dry_run["diff"]["to_write"])
- assert await git_harness.vfs.read(
- "viking://resources/proj/a.md",
- ctx=git_harness.ctx,
- ) == b"v2"
+ assert (
+ await git_harness.vfs.read(
+ "viking://resources/proj/a.md",
+ ctx=git_harness.ctx,
+ )
+ == b"v2"
+ )
assert len(git_harness.client.snapshot.log()) == len(before_log)
@@ -398,19 +400,13 @@ async def test_snapshot_namespace_gitignore_roundtrip(git_harness):
assert await client.snapshot.get_gitignore() == "*.log\n"
# The rule must affect commits: a .log file is skipped, a .md file kept.
- await git_harness.vfs.write_file(
- "viking://resources/keep.md", b"keep", ctx=git_harness.ctx
- )
- await git_harness.vfs.write_file(
- "viking://resources/skip.log", b"skip", ctx=git_harness.ctx
- )
+ await git_harness.vfs.write_file("viking://resources/keep.md", b"keep", ctx=git_harness.ctx)
+ await git_harness.vfs.write_file("viking://resources/skip.log", b"skip", ctx=git_harness.ctx)
commit = await client.snapshot.commit(message="with ignore")
assert commit["result"] == "created"
assert commit["ignored"] == 1
- assert await client.snapshot.show(
- "main", path="viking://resources/keep.md"
- ) == b"keep"
+ assert await client.snapshot.show("main", path="viking://resources/keep.md") == b"keep"
with pytest.raises(AGFSNotFoundError):
await client.snapshot.show("main", path="viking://resources/skip.log")
diff --git a/tests/client/test_git_versioning_http.py b/tests/client/test_git_versioning_http.py
index 3323645f7..fbc4bf30e 100644
--- a/tests/client/test_git_versioning_http.py
+++ b/tests/client/test_git_versioning_http.py
@@ -24,19 +24,18 @@ import httpx
import pytest
import pytest_asyncio
-ragfs_python = pytest.importorskip("ragfs_python")
-
from openviking.models.embedder.base import DenseEmbedderBase, EmbedResult
from openviking.server.app import create_app
from openviking.server.config import ServerConfig
from openviking.server.identity import RequestContext, Role
from openviking.service.core import OpenVikingService
-from openviking.storage.transaction import reset_lock_manager
from openviking_cli.client.http import AsyncHTTPClient
from openviking_cli.session.user_id import UserIdentifier
from openviking_cli.utils.config.embedding_config import EmbeddingConfig
from openviking_cli.utils.config.vlm_config import VLMConfig
+pytest.importorskip("ragfs_python")
+
pytestmark = pytest.mark.asyncio
@@ -86,7 +85,6 @@ def http_temp_dir():
@pytest_asyncio.fixture(scope="function")
async def http_service(http_temp_dir: Path, monkeypatch):
"""Stand up a real OpenVikingService backed by a temp data dir."""
- reset_lock_manager()
fake_embedder_cls = _install_fake_embedder(monkeypatch)
_install_fake_vlm(monkeypatch)
@@ -107,7 +105,6 @@ async def http_service(http_temp_dir: Path, monkeypatch):
yield svc
finally:
await svc.close()
- reset_lock_manager()
@pytest_asyncio.fixture(scope="function")
@@ -195,6 +192,7 @@ async def test_http_log_filters_repeated_paths_end_to_end(http_app, http_service
headers=_AUTH_HEADERS,
timeout=30.0,
) as client:
+
async def commit(uri: str, body: bytes, message: str) -> dict:
await _write_blob(http_service, uri, body)
response = await client.post(
diff --git a/tests/client/test_import_export.py b/tests/client/test_import_export.py
index ff8263f5f..5fd735617 100644
--- a/tests/client/test_import_export.py
+++ b/tests/client/test_import_export.py
@@ -12,7 +12,6 @@ from pathlib import Path
import pytest
from openviking import AsyncOpenViking
-from openviking.storage.transaction import release_all_locks
class TestExportOvpack:
@@ -100,7 +99,6 @@ class TestImportOvpack:
await client.export_ovpack(original_uri, str(export_path))
# Delete original resource
- await release_all_locks()
await client.rm(original_uri, recursive=True)
# Import
diff --git a/tests/integration/test_full_workflow.py b/tests/integration/test_full_workflow.py
index b14bd417b..285addf23 100644
--- a/tests/integration/test_full_workflow.py
+++ b/tests/integration/test_full_workflow.py
@@ -10,7 +10,6 @@ import pytest_asyncio
from openviking import AsyncOpenViking
from openviking.message import TextPart
-from openviking.storage.transaction import release_all_locks
@pytest_asyncio.fixture(scope="function")
@@ -176,7 +175,6 @@ class TestImportExportWorkflow:
assert export_path.exists()
# 4. Delete original resource
- await release_all_locks()
await client.rm(original_uri, recursive=True)
# 5. Import
diff --git a/tests/metrics/collectors/test_state_collectors.py b/tests/metrics/collectors/test_state_collectors.py
index 539a97499..9f8491245 100644
--- a/tests/metrics/collectors/test_state_collectors.py
+++ b/tests/metrics/collectors/test_state_collectors.py
@@ -3,16 +3,12 @@
from __future__ import annotations
-import time
-
-from openviking.metrics.collectors.lock import LockCollector
from openviking.metrics.collectors.observer_health import ObserverHealthCollector
from openviking.metrics.collectors.queue import QueueCollector
from openviking.metrics.collectors.task_tracker import TaskTrackerCollector
from openviking.metrics.collectors.vikingdb import VikingDBCollector
from openviking.metrics.core.registry import MetricRegistry
from openviking.metrics.datasources.observer_state import (
- LockStateDataSource,
ObserverStateDataSource,
VikingDBStateDataSource,
)
@@ -233,31 +229,6 @@ def test_model_usage_collector_failure_reuses_last_available_state_with_valid_ze
assert 'openviking_model_usage_available{model_type="rerank",valid="0"} 0.0' in text
-def test_lock_collector_counts_active_and_stale(monkeypatch):
- class Handle:
- def __init__(self, locks: int, last_active_at: float) -> None:
- self.locks = [object()] * locks
- self.last_active_at = last_active_at
-
- class DummyLockManager:
- def get_active_handles(self):
- now = time.time()
- return {
- "a": Handle(locks=2, last_active_at=now - 10),
- "b": Handle(locks=1, last_active_at=now - 1000),
- }
-
- monkeypatch.setattr(
- "openviking.metrics.datasources.observer_state.get_lock_manager",
- lambda: DummyLockManager(),
- )
- registry = MetricRegistry()
- LockCollector(data_source=LockStateDataSource()).collect(registry)
- text = PrometheusExporter(registry=registry).render()
- assert "openviking_lock_active 3.0" in text
- assert "openviking_lock_stale 1.0" in text
-
-
def test_vikingdb_collector_exports_health_and_count(monkeypatch):
class DummyVikingDB:
collection_name = "my_collection"
diff --git a/tests/misc/test_config_validation.py b/tests/misc/test_config_validation.py
index 6b819798c..dccbfcffa 100644
--- a/tests/misc/test_config_validation.py
+++ b/tests/misc/test_config_validation.py
@@ -584,9 +584,30 @@ def test_ragfs_binding_config_builds_single_binding_dict_for_local_backend(tmp_p
"provider_type": 7,
},
"cache": agfs_config.cache.model_dump(mode="json"),
+ "pathlock": {
+ "provider": "filesystem",
+ "lock_expire_secs": 300.0,
+ },
}
+def test_agfs_pathlock_config_validates_provider_and_expiry(tmp_path):
+ """PathLock config accepts built-ins and rejects unsafe expiry values."""
+ config = AGFSConfig(
+ path=str(tmp_path),
+ backend="local",
+ pathlock={"provider": "memory", "lock_expire_secs": 60.0},
+ )
+
+ assert config.pathlock.provider == "memory"
+ assert config.pathlock.lock_expire_secs == 60.0
+
+ with pytest.raises(ValueError, match="pathlock provider"):
+ AGFSConfig(path=str(tmp_path), pathlock={"provider": "redis"})
+ with pytest.raises(ValueError, match="lock_expire_secs"):
+ AGFSConfig(path=str(tmp_path), pathlock={"lock_expire_secs": 0.0})
+
+
def test_create_agfs_client_uses_single_binding_config_object(monkeypatch, tmp_path):
agfs_config = AGFSConfig(
path=str(tmp_path),
diff --git a/tests/misc/test_debug_service.py b/tests/misc/test_debug_service.py
index 90de9062d..922e59068 100644
--- a/tests/misc/test_debug_service.py
+++ b/tests/misc/test_debug_service.py
@@ -202,9 +202,9 @@ class TestObserverService:
rerank_instance=None,
)
- @patch("openviking.service.debug_service.get_lock_manager")
+ @patch("openviking.service.debug_service.run_async")
+ @patch("openviking.service.debug_service.get_viking_fs")
@patch("openviking.service.debug_service.RetrievalObserver")
- @patch("openviking.service.debug_service.LockObserver")
@patch("openviking.service.debug_service.ModelsObserver")
@patch("openviking.service.debug_service.VikingDBObserver")
@patch("openviking.service.debug_service.QueueObserver")
@@ -215,9 +215,9 @@ class TestObserverService:
mock_queue_cls,
mock_vikingdb_cls,
mock_models_cls,
- mock_lock_cls,
mock_retrieval_cls,
- mock_get_lock_mgr,
+ mock_get_viking_fs,
+ mock_run_async,
):
"""Test system property when all components are healthy."""
# Setup mocks
@@ -225,7 +225,6 @@ class TestObserverService:
mock_queue_cls,
mock_vikingdb_cls,
mock_models_cls,
- mock_lock_cls,
mock_retrieval_cls,
]:
mock_observer = MagicMock()
@@ -234,8 +233,15 @@ class TestObserverService:
mock_observer.get_status_table.return_value = "OK"
mock_cls.return_value = mock_observer
- # Mock get_lock_manager to return a MagicMock
- mock_get_lock_mgr.return_value = MagicMock()
+ # Mock get_viking_fs to return a viking_fs with pathlock_observe
+ mock_viking_fs = MagicMock()
+ mock_get_viking_fs.return_value = mock_viking_fs
+ mock_run_async.return_value = {
+ "active_locks": 0,
+ "waiting_locks": 0,
+ "stale_locks_removed": 0,
+ "conflicts": [],
+ }
mock_config = MagicMock(spec=["vlm"]) # Only allow vlm attribute
mock_config.vlm.get_vlm_instance.return_value = MagicMock()
@@ -248,9 +254,9 @@ class TestObserverService:
non_transaction_errors = [e for e in status.errors if "transaction" not in e]
assert non_transaction_errors == []
- @patch("openviking.service.debug_service.get_lock_manager")
+ @patch("openviking.service.debug_service.run_async")
+ @patch("openviking.service.debug_service.get_viking_fs")
@patch("openviking.service.debug_service.RetrievalObserver")
- @patch("openviking.service.debug_service.LockObserver")
@patch("openviking.service.debug_service.ModelsObserver")
@patch("openviking.service.debug_service.VikingDBObserver")
@patch("openviking.service.debug_service.QueueObserver")
@@ -261,9 +267,9 @@ class TestObserverService:
mock_queue_cls,
mock_vikingdb_cls,
mock_models_cls,
- mock_lock_cls,
mock_retrieval_cls,
- mock_get_lock_mgr,
+ mock_get_viking_fs,
+ mock_run_async,
):
"""Test system property when some components have errors."""
# Queue has errors
@@ -287,16 +293,22 @@ class TestObserverService:
mock_models.get_status_table.return_value = "Error"
mock_models_cls.return_value = mock_models
- # Lock and Retrieval are healthy
- for mock_cls in [mock_lock_cls, mock_retrieval_cls]:
- mock_observer = MagicMock()
- mock_observer.is_healthy.return_value = True
- mock_observer.has_errors.return_value = False
- mock_observer.get_status_table.return_value = "OK"
- mock_cls.return_value = mock_observer
-
- # Mock get_lock_manager to return a MagicMock
- mock_get_lock_mgr.return_value = MagicMock()
+ # Retrieval is healthy
+ mock_retrieval = MagicMock()
+ mock_retrieval.is_healthy.return_value = True
+ mock_retrieval.has_errors.return_value = False
+ mock_retrieval.get_status_table.return_value = "OK"
+ mock_retrieval_cls.return_value = mock_retrieval
+
+ # Mock lock (pathlock_observe) as healthy
+ mock_viking_fs = MagicMock()
+ mock_get_viking_fs.return_value = mock_viking_fs
+ mock_run_async.return_value = {
+ "active_locks": 0,
+ "waiting_locks": 0,
+ "stale_locks_removed": 0,
+ "conflicts": [],
+ }
mock_config = MagicMock(spec=["vlm"]) # Only allow vlm attribute
mock_config.vlm.get_vlm_instance.return_value = MagicMock()
@@ -310,7 +322,8 @@ class TestObserverService:
assert "queue has errors" in non_transaction_errors
assert "models has errors" in non_transaction_errors
- @patch("openviking.service.debug_service.get_lock_manager")
+ @patch("openviking.service.debug_service.run_async")
+ @patch("openviking.service.debug_service.get_viking_fs")
@patch("openviking.service.debug_service.get_queue_manager")
@patch("openviking.service.debug_service.QueueObserver")
@patch("openviking.service.debug_service.VikingDBObserver")
@@ -321,7 +334,8 @@ class TestObserverService:
mock_vikingdb_cls,
mock_queue_cls,
mock_get_queue_mgr,
- mock_get_lock_mgr,
+ mock_get_viking_fs,
+ mock_run_async,
):
"""Test is_healthy returns True when system is healthy."""
for mock_cls in [mock_queue_cls, mock_vikingdb_cls, mock_models_cls]:
@@ -331,7 +345,14 @@ class TestObserverService:
mock_observer.get_status_table.return_value = "OK"
mock_cls.return_value = mock_observer
- mock_get_lock_mgr.return_value = MagicMock()
+ mock_viking_fs = MagicMock()
+ mock_get_viking_fs.return_value = mock_viking_fs
+ mock_run_async.return_value = {
+ "active_locks": 0,
+ "waiting_locks": 0,
+ "stale_locks_removed": 0,
+ "conflicts": [],
+ }
mock_config = MagicMock(spec=["vlm"])
mock_config.vlm.get_vlm_instance.return_value = MagicMock()
diff --git a/tests/misc/test_resource_processor_mv.py b/tests/misc/test_resource_processor_mv.py
index b364be0bc..9090efbd0 100644
--- a/tests/misc/test_resource_processor_mv.py
+++ b/tests/misc/test_resource_processor_mv.py
@@ -39,59 +39,36 @@ class _CtxMgr:
return False
-class _FakeLockManager:
+class _FakePathLock:
def __init__(self, *, busy_tree_paths=None):
- from openviking.storage.transaction.lock_handle import LockHandle
-
- self._lock_handle_cls = LockHandle
- self._handles = {}
- self.acquired_exact_paths = []
- self.acquired_tree_paths = []
- self.tree_attempts = []
+ self._next_id = 0
+ self.acquired_tree_paths: list[str] = []
+ self.tree_attempts: list[tuple[str, float]] = []
self.busy_tree_paths = set(busy_tree_paths or [])
- def create_handle(self):
- handle = self._lock_handle_cls()
- self._handles[handle.id] = handle
- return handle
+ def _new_lease(self):
+ self._next_id += 1
+ return {"id": f"lock-{self._next_id}"}
- async def acquire_exact_path_batch(self, handle, paths, timeout=None):
- for path in paths:
- lock_path = f"exact:{path}"
- handle.add_lock(lock_path)
- self.acquired_exact_paths.append(path)
- return True
+ async def pathlock_acquire_tree(self, path, timeout_secs=0.0):
+ from openviking.storage.errors import LockAcquisitionError
- async def acquire_tree(self, handle, path, timeout=None):
- self.tree_attempts.append((path, timeout))
+ self.tree_attempts.append((path, timeout_secs))
if path in self.busy_tree_paths:
- return False
- lock_path = f"tree:{path}"
- handle.add_lock(lock_path)
+ raise LockAcquisitionError(f"busy: {path}")
self.acquired_tree_paths.append(path)
- return True
+ return self._new_lease()
- async def release_selected(self, handle, lock_paths):
- for path in lock_paths:
- handle.remove_lock(path)
-
- async def release(self, handle):
- for path in list(handle.locks):
- handle.remove_lock(path)
- self._handles.pop(handle.id, None)
-
- def get_handle(self, handle_id):
- handle = self._handles.get(handle_id)
- if handle and handle.locks:
- return handle
- return None
+ async def pathlock_release(self, lease):
+ pass
class _FakeVikingFS:
- def __init__(self, *, exists_result=False, existing_uris=None):
+ def __init__(self, *, exists_result=False, existing_uris=None, pathlock=None):
self.agfs = SimpleNamespace(
write=MagicMock(return_value={"status": "ok"}),
)
+ self._async_agfs = pathlock or _FakePathLock()
self._exists_result = exists_result
self._existing_uris = set(existing_uris or [])
self.exists_calls = []
@@ -110,12 +87,12 @@ class _FakeVikingFS:
async def mkdir(self, uri, exist_ok=False, ctx=None):
return None
- async def delete_temp(self, temp_dir_path, ctx=None):
- self.delete_temp_calls.append(temp_dir_path)
+ async def delete_temp(self, temp_dir_path, ctx=None, lease_ref=None):
+ self.delete_temp_calls.append((temp_dir_path, lease_ref))
return None
- async def persist_temp_tree(self, temp_uri, target_uri, ctx=None):
- self.persist_calls.append((temp_uri, target_uri))
+ async def persist_temp_tree(self, temp_uri, target_uri, ctx=None, lease_ref=None):
+ self.persist_calls.append((temp_uri, target_uri, lease_ref))
self.agfs.write(self._uri_to_path(target_uri, ctx=ctx), b"content")
async def glob(self, pattern, uri=None, ctx=None):
@@ -135,7 +112,6 @@ async def test_resource_processor_first_add_summarizes_from_committed_uri(monkey
from openviking.utils.resource_processor import ResourceProcessor
fake_fs = _FakeVikingFS()
- fake_lock_manager = _FakeLockManager()
summarize_calls = []
monkeypatch.setattr(
@@ -143,10 +119,6 @@ async def test_resource_processor_first_add_summarizes_from_committed_uri(monkey
lambda: _DummyTelemetry(),
)
_patch_viking_fs(monkeypatch, fake_fs)
- monkeypatch.setattr(
- "openviking.storage.transaction.get_lock_manager",
- lambda: fake_lock_manager,
- )
rp = ResourceProcessor(vikingdb=_DummyVikingDB(), media_storage=None)
rp._get_media_processor = MagicMock()
@@ -176,8 +148,10 @@ async def test_resource_processor_first_add_summarizes_from_committed_uri(monkey
assert result["status"] == "success"
assert result["root_uri"] == "viking://resources/root"
- assert fake_fs.persist_calls == [("viking://temp/root_tmp", "viking://resources/root")]
- assert fake_fs.delete_temp_calls == ["viking://temp/tmpdir"]
+ assert fake_fs.persist_calls == [
+ ("viking://temp/root_tmp", "viking://resources/root", {"id": "lock-1"})
+ ]
+ assert fake_fs.delete_temp_calls == [("viking://temp/tmpdir", None)]
assert summarize_calls[0]["temp_uris"] == ["viking://resources/root"]
assert summarize_calls[0]["target_preexisting"] is False
@@ -187,7 +161,6 @@ async def test_resource_processor_second_add_preserves_temp_uri_for_incremental(
from openviking.utils.resource_processor import ResourceProcessor
fake_fs = _FakeVikingFS(exists_result=True)
- fake_lock_manager = _FakeLockManager()
summarize_calls = []
monkeypatch.setattr(
@@ -195,10 +168,6 @@ async def test_resource_processor_second_add_preserves_temp_uri_for_incremental(
lambda: _DummyTelemetry(),
)
_patch_viking_fs(monkeypatch, fake_fs)
- monkeypatch.setattr(
- "openviking.storage.transaction.get_lock_manager",
- lambda: fake_lock_manager,
- )
rp = ResourceProcessor(vikingdb=_DummyVikingDB(), media_storage=None)
rp._get_media_processor = MagicMock()
@@ -237,8 +206,8 @@ async def test_resource_processor_second_add_preserves_temp_uri_for_incremental(
async def test_resource_processor_auto_candidate_skips_existing_and_busy(monkeypatch):
from openviking.utils.resource_processor import ResourceProcessor
- fake_fs = _FakeVikingFS(existing_uris={"viking://resources/root"})
- fake_lock_manager = _FakeLockManager(busy_tree_paths={"/mock/resources/root_1"})
+ fake_pathlock = _FakePathLock(busy_tree_paths={"/mock/resources/root_1"})
+ fake_fs = _FakeVikingFS(existing_uris={"viking://resources/root"}, pathlock=fake_pathlock)
summarize_calls = []
monkeypatch.setattr(
@@ -246,10 +215,6 @@ async def test_resource_processor_auto_candidate_skips_existing_and_busy(monkeyp
lambda: _DummyTelemetry(),
)
_patch_viking_fs(monkeypatch, fake_fs)
- monkeypatch.setattr(
- "openviking.storage.transaction.get_lock_manager",
- lambda: fake_lock_manager,
- )
rp = ResourceProcessor(vikingdb=_DummyVikingDB(), media_storage=None)
rp._get_media_processor = MagicMock()
@@ -285,12 +250,13 @@ async def test_resource_processor_auto_candidate_skips_existing_and_busy(monkeyp
"viking://resources/root_1",
"viking://resources/root_2",
]
- assert fake_lock_manager.tree_attempts == [
+ assert fake_pathlock.tree_attempts == [
("/mock/resources/root_1", 0.0),
("/mock/resources/root_2", 0.0),
]
- assert fake_lock_manager.acquired_exact_paths == []
- assert fake_lock_manager.acquired_tree_paths == ["/mock/resources/root_2"]
+ assert fake_pathlock.acquired_tree_paths == ["/mock/resources/root_2"]
assert summarize_calls[0]["temp_uris"] == ["viking://resources/root_2"]
assert summarize_calls[0]["target_preexisting"] is False
- assert fake_fs.persist_calls == [("viking://temp/root_tmp", "viking://resources/root_2")]
+ assert fake_fs.persist_calls == [
+ ("viking://temp/root_tmp", "viking://resources/root_2", {"id": "lock-1"})
+ ]
diff --git a/tests/parse/test_feishu_parser_api.py b/tests/parse/test_feishu_parser_api.py
index 22a732b34..26fcfba7f 100644
--- a/tests/parse/test_feishu_parser_api.py
+++ b/tests/parse/test_feishu_parser_api.py
@@ -440,10 +440,6 @@ async def test_uat_producer_payload_reaches_worker_without_persisting_token(monk
"openviking.storage.queuefs.get_queue_manager",
Mock(return_value=queue_manager),
)
- monkeypatch.setattr(
- "openviking.storage.transaction.get_lock_manager",
- Mock(return_value=SimpleNamespace()),
- )
service = ResourceService(
viking_fs=SimpleNamespace(),
@@ -513,7 +509,12 @@ async def test_uat_producer_payload_reaches_worker_without_persisting_token(monk
@pytest.mark.asyncio
async def test_local_prepared_job_uses_add_resource_queue(monkeypatch):
root_uri = "viking://resources/script"
- resource_lock = SimpleNamespace(to_handoff=Mock(return_value=None))
+ resource_lock = {"lease_ref": "lock-1"}
+ agfs = SimpleNamespace(
+ pathlock_to_handoff=AsyncMock(return_value={"handle_id": "lock-1"}),
+ pathlock_handoff=AsyncMock(),
+ pathlock_release=AsyncMock(),
+ )
resource_processor = SimpleNamespace(
process_resource=AsyncMock(
return_value={
@@ -526,7 +527,7 @@ async def test_local_prepared_job_uses_add_resource_queue(monkeypatch):
)
service = ResourceService(
- viking_fs=SimpleNamespace(),
+ viking_fs=SimpleNamespace(_async_agfs=agfs),
resource_processor=resource_processor,
skill_processor=SimpleNamespace(),
)
@@ -556,6 +557,8 @@ async def test_local_prepared_job_uses_add_resource_queue(monkeypatch):
call = service._enqueue_add_resource_job.await_args
assert call.kwargs["queue_name"] == QueueManager.ADD_RESOURCE
assert call.args[0].prepared == {"root_uri": root_uri}
+ assert call.args[0].lock_handoff == {"handle_id": "lock-1"}
+ agfs.pathlock_to_handoff.assert_awaited_once_with(resource_lock)
@pytest.mark.asyncio
@@ -569,6 +572,7 @@ async def test_uat_producer_cancellation_respects_queue_ownership(
submit_url = AsyncMock(return_value="response-1")
enqueue = AsyncMock()
handoff = AsyncMock()
+ release = AsyncMock()
if cancel_stage == "submit":
submit_url.side_effect = asyncio.CancelledError
elif cancel_stage == "enqueue":
@@ -587,19 +591,17 @@ async def test_uat_producer_cancellation_respects_queue_ownership(
fail=AsyncMock(),
)
queue_manager = SimpleNamespace(enqueue=enqueue)
- lock_lease = SimpleNamespace(
- to_handoff=Mock(
- return_value=SimpleNamespace(
- to_dict=Mock(
- return_value={
- "handle_id": "lock-1",
- "lock_paths": ["/resources/fixed"],
- }
- )
- )
+ lock_lease = {"lease_ref": "lock-1"}
+ agfs = SimpleNamespace(
+ pathlock_acquire_tree=AsyncMock(return_value=lock_lease),
+ pathlock_to_handoff=AsyncMock(
+ return_value={
+ "handle_id": "lock-1",
+ "lock_paths": ["/resources/fixed"],
+ }
),
- handoff=handoff,
- close=AsyncMock(),
+ pathlock_handoff=handoff,
+ pathlock_release=release,
)
monkeypatch.setattr(
"openviking.service.task_tracker.get_task_tracker",
@@ -609,17 +611,12 @@ async def test_uat_producer_cancellation_respects_queue_ownership(
"openviking.storage.queuefs.get_queue_manager",
Mock(return_value=queue_manager),
)
- monkeypatch.setattr(
- "openviking.storage.transaction.get_lock_manager",
- Mock(return_value=SimpleNamespace()),
- )
- monkeypatch.setattr(
- "openviking.storage.transaction.OwnedLockLease.acquire_tree",
- AsyncMock(return_value=lock_lease),
- )
service = ResourceService(
- viking_fs=SimpleNamespace(_uri_to_path=lambda _uri, ctx: "/resources/fixed"),
+ viking_fs=SimpleNamespace(
+ _uri_to_path=lambda _uri, ctx: "/resources/fixed",
+ _async_agfs=agfs,
+ ),
resource_processor=resource_processor,
skill_processor=SimpleNamespace(),
)
@@ -647,7 +644,7 @@ async def test_uat_producer_cancellation_respects_queue_ownership(
args={"feishu_access_token": "u-secret"},
)
- lock_lease.close.assert_awaited_once_with()
+ release.assert_awaited_once_with(lock_lease)
task_tracker.create.assert_not_awaited()
task_tracker.fail.assert_not_awaited()
if cancel_stage == "submit":
@@ -813,6 +810,7 @@ async def test_add_resource_processor_persists_final_resource_uri(monkeypatch):
service,
asyncio.get_running_loop(),
QueueManager.ADD_RESOURCE,
+ SimpleNamespace(_async_agfs=SimpleNamespace(pathlock_release=AsyncMock())),
)
msg = AddResourceMsg(
task_id="task-1",
diff --git a/tests/parse/test_markdown_link_rewrite.py b/tests/parse/test_markdown_link_rewrite.py
index 2f99ba884..a1f26f494 100644
--- a/tests/parse/test_markdown_link_rewrite.py
+++ b/tests/parse/test_markdown_link_rewrite.py
@@ -551,7 +551,7 @@ class TestImageLinkSplit:
import openviking.parse.image_rewrite as image_rewrite_mod
with patch.object(image_rewrite_mod, "get_viking_fs", return_value=fake):
- stats = await rewrite_image_uris(root, lock_handle=None)
+ stats = await rewrite_image_uris(root, lease_ref=None)
assert stats["references_rewritten"] == 2, stats
page = _decode(fake.files[f"{root}/guides/page/page.md"])
@@ -601,7 +601,7 @@ class TestRewriteImageUris:
}
with self._patched(fake):
- stats = await rewrite_image_uris(root, lock_handle=None)
+ stats = await rewrite_image_uris(root, lease_ref=None)
assert stats == {"files_processed": 1, "references_rewritten": 1}
assert _decode(fake.files[f"{root}/index/index.md"]) == (f"![p]({root}/index/logo.png)")
@@ -623,7 +623,7 @@ class TestRewriteImageUris:
}
with self._patched(fake):
- stats = await rewrite_image_uris(root, lock_handle=None)
+ stats = await rewrite_image_uris(root, lease_ref=None)
assert stats == {"files_processed": 1, "references_rewritten": 1}
assert _decode(fake.files[f"{root}/big/标题/章一/部分_1.md"]) == (
@@ -647,7 +647,7 @@ class TestRewriteImageUris:
}
with self._patched(fake):
- stats = await rewrite_image_uris(root, lock_handle=None)
+ stats = await rewrite_image_uris(root, lease_ref=None)
assert stats == {"files_processed": 1, "references_rewritten": 1}
assert _decode(fake.files[f"{root}/doc.md"]) == f"![p]({root}/logo.png)"
@@ -736,7 +736,7 @@ class TestRewriteImageUris:
fake.files[f"{root}/{u[len(src_prefix) :]}"] = fake.files[u]
with self._patched(fake):
- stats = await rewrite_image_uris(root, lock_handle=None)
+ stats = await rewrite_image_uris(root, lease_ref=None)
assert stats["files_processed"] == 2, stats
index_md = _decode(fake.files[f"{root}/index/index.md"])
diff --git a/tests/server/conftest.py b/tests/server/conftest.py
index 0904c3638..5e85ed22a 100644
--- a/tests/server/conftest.py
+++ b/tests/server/conftest.py
@@ -24,7 +24,6 @@ from openviking.server.config import ServerConfig
from openviking.server.identity import RequestContext, Role
from openviking.service.core import OpenVikingService
from openviking.storage.queuefs import QueueManager, SessionCommitMsg, get_queue_manager
-from openviking.storage.transaction import reset_lock_manager
from openviking_cli.session.user_id import UserIdentifier
from openviking_cli.utils.config.embedding_config import EmbeddingConfig
from openviking_cli.utils.config.vlm_config import VLMConfig
@@ -168,7 +167,6 @@ def upload_temp_dir(temp_dir: Path, monkeypatch) -> Path:
@pytest_asyncio.fixture(scope="function")
async def service(temp_dir: Path, monkeypatch):
"""Create and initialize an OpenVikingService in embedded mode."""
- reset_lock_manager()
fake_embedder_cls = _install_fake_embedder(monkeypatch)
_install_fake_vlm(monkeypatch)
svc = OpenVikingService(
@@ -179,7 +177,6 @@ async def service(temp_dir: Path, monkeypatch):
_install_session_commit_queue_fallback(svc, monkeypatch)
yield svc
await svc.close()
- reset_lock_manager()
@pytest_asyncio.fixture(scope="function")
@@ -233,7 +230,6 @@ async def client_with_resource(client, service, sample_markdown_file):
async def running_server(temp_dir: Path, monkeypatch):
"""Start a real uvicorn server in a background thread."""
await AsyncOpenViking.reset()
- reset_lock_manager()
fake_embedder_cls = _install_fake_embedder(monkeypatch)
_install_fake_vlm(monkeypatch)
diff --git a/tests/server/test_admin_api.py b/tests/server/test_admin_api.py
index 7f7695d49..b9e8c7100 100644
--- a/tests/server/test_admin_api.py
+++ b/tests/server/test_admin_api.py
@@ -43,19 +43,6 @@ def _seed_secret(user_id: str, seed: str) -> str:
ROOT_KEY = "admin-api-test-root-key-abcdef1234567890ab"
-class _NoopLockContext:
- """The lightweight fake storage does not exercise transaction locking."""
-
- def __init__(self, *_args, **_kwargs):
- pass
-
- async def __aenter__(self):
- return self
-
- async def __aexit__(self, *_args):
- return False
-
-
class _FakeAGFS:
def __init__(self):
self._files = {}
@@ -148,12 +135,6 @@ def _build_lightweight_admin_test_app() -> FastAPI:
@pytest_asyncio.fixture(scope="function")
async def lightweight_admin_app(monkeypatch):
- monkeypatch.setattr(
- "openviking.server.api_keys.legacy.get_lock_manager", lambda: None
- )
- monkeypatch.setattr(
- "openviking.server.api_keys.legacy.LockContext", _NoopLockContext
- )
app = _build_lightweight_admin_test_app()
await app.state.api_key_manager.load()
return app
diff --git a/tests/server/test_api_key_manager.py b/tests/server/test_api_key_manager.py
index 309c02efe..c25177145 100644
--- a/tests/server/test_api_key_manager.py
+++ b/tests/server/test_api_key_manager.py
@@ -15,7 +15,6 @@ from openviking.server.api_keys import APIKeyManager
from openviking.server.api_keys.legacy import ACCOUNTS_PATH
from openviking.server.identity import Role
from openviking.service.core import OpenVikingService
-from openviking.storage.transaction import LockContext, get_lock_manager
from openviking_cli.exceptions import (
AlreadyExistsError,
InvalidArgumentError,
@@ -171,32 +170,54 @@ async def test_register_user(manager: APIKeyManager):
async def test_concurrent_registry_writes_wait_for_locks(manager: APIKeyManager):
first_account = _uid()
second_account = _uid()
+ accounts_block = asyncio.Event()
+ original_acquire = manager._legacy._async_agfs.pathlock_acquire_exact
- async with LockContext(get_lock_manager(), [ACCOUNTS_PATH], lock_mode="exact"):
- account_tasks = [
- asyncio.create_task(manager.create_account(first_account, "alice")),
- asyncio.create_task(manager.create_account(second_account, "bob")),
- ]
- await asyncio.sleep(0.05)
- assert all(not task.done() for task in account_tasks)
+ async def blocked_acquire(path, timeout_secs=10.0, owner_lease_ref=None, *, fs_ctx=None):
+ del owner_lease_ref, fs_ctx
+ if path == ACCOUNTS_PATH:
+ await accounts_block.wait()
+ return await original_acquire(path, timeout_secs=timeout_secs)
+ manager._legacy._async_agfs.pathlock_acquire_exact = blocked_acquire
+
+ account_tasks = [
+ asyncio.create_task(manager.create_account(first_account, "alice")),
+ asyncio.create_task(manager.create_account(second_account, "bob")),
+ ]
+ await asyncio.sleep(0.05)
+ assert all(not task.done() for task in account_tasks)
+
+ accounts_block.set()
await asyncio.gather(*account_tasks)
accounts = await manager._read_json(ACCOUNTS_PATH)
assert {first_account, second_account} <= set(accounts["accounts"])
users_path = f"/local/{first_account}/_system/users.json"
- async with LockContext(get_lock_manager(), [users_path], lock_mode="exact"):
- user_tasks = [
- asyncio.create_task(manager.register_user(first_account, "bob")),
- asyncio.create_task(manager.register_user(first_account, "carol")),
- ]
- await asyncio.sleep(0.05)
- assert all(not task.done() for task in user_tasks)
+ users_block = asyncio.Event()
+
+ async def blocked_users_acquire(path, timeout_secs=10.0, owner_lease_ref=None, *, fs_ctx=None):
+ del owner_lease_ref, fs_ctx
+ if path == users_path:
+ await users_block.wait()
+ return await original_acquire(path, timeout_secs=timeout_secs)
+ manager._legacy._async_agfs.pathlock_acquire_exact = blocked_users_acquire
+
+ user_tasks = [
+ asyncio.create_task(manager.register_user(first_account, "bob")),
+ asyncio.create_task(manager.register_user(first_account, "carol")),
+ ]
+ await asyncio.sleep(0.05)
+ assert all(not task.done() for task in user_tasks)
+
+ users_block.set()
await asyncio.gather(*user_tasks)
users = await manager._read_json(users_path)
assert set(users["users"]) == {"alice", "bob", "carol"}
+ manager._legacy._async_agfs.pathlock_acquire_exact = original_acquire
+
async def test_register_duplicate_user_raises(manager: APIKeyManager):
"""Registering duplicate user should raise AlreadyExistsError."""
diff --git a/tests/server/test_content_batch_write.py b/tests/server/test_content_batch_write.py
index 8841d9f57..225023b0c 100644
--- a/tests/server/test_content_batch_write.py
+++ b/tests/server/test_content_batch_write.py
@@ -15,21 +15,18 @@ from openviking_cli.exceptions import (
from openviking_cli.session.user_id import UserIdentifier
-class _LockManager:
+class _PathLockClient:
def __init__(self):
self.held = False
self.releases = 0
- def create_handle(self):
- return object()
-
- async def acquire_tree(self, handle, path):
- del handle, path
+ async def pathlock_acquire_tree(self, path):
+ del path
self.held = True
- return True
+ return {"lease_ref": "lock-1"}
- async def release(self, handle):
- del handle
+ async def pathlock_release(self, lease):
+ assert lease == {"lease_ref": "lock-1"}
self.held = False
self.releases += 1
@@ -40,6 +37,7 @@ class _VFS:
self.files = dict(files or {})
self.fail_uri = fail_uri
self.writes = []
+ self._async_agfs = _PathLockClient()
def _ensure_mutable_access(self, uri, ctx):
del uri, ctx
@@ -66,9 +64,9 @@ class _VFS:
value = await self.read_file(uri, ctx=ctx)
return value.encode() if isinstance(value, str) else value
- async def write_file(self, uri, content, ctx=None, lock_handle=None):
+ async def write_file(self, uri, content, ctx=None, lease_ref=None):
del ctx
- assert lock_handle is not None
+ assert lease_ref is not None
if uri == self.fail_uri:
raise OSError("injected write failure")
self.files[uri] = content
@@ -88,10 +86,9 @@ async def test_batch_checks_all_preconditions_before_any_write(monkeypatch):
root = "viking://resources/wiki"
existing = f"{root}/existing.md"
created = f"{root}/new.md"
- locks = _LockManager()
vfs = _VFS(root, {existing: "newer"})
+ locks = vfs._async_agfs
coordinator = ContentWriteCoordinator(vfs)
- monkeypatch.setattr(content_write_module, "get_lock_manager", lambda: locks)
refreshed = []
async def refresh(**kwargs):
@@ -130,10 +127,9 @@ async def test_batch_releases_tree_lock_before_one_aggregated_refresh(monkeypatc
root = "viking://resources/wiki"
a = f"{root}/a.md"
b = f"{root}/b.md"
- locks = _LockManager()
vfs = _VFS(root)
+ locks = vfs._async_agfs
coordinator = ContentWriteCoordinator(vfs)
- monkeypatch.setattr(content_write_module, "get_lock_manager", lambda: locks)
calls = []
async def refresh(**kwargs):
@@ -162,12 +158,10 @@ async def test_batch_releases_tree_lock_before_one_aggregated_refresh(monkeypatc
async def test_batch_writes_and_hashes_binary_content(monkeypatch):
root = "viking://resources/wiki"
image = f"{root}/figure.png"
- locks = _LockManager()
original = b"\x89PNG\r\n\x1a\nold"
replacement = b"\x89PNG\r\n\x1a\nnew"
vfs = _VFS(root, {image: original})
coordinator = ContentWriteCoordinator(vfs)
- monkeypatch.setattr(content_write_module, "get_lock_manager", lambda: locks)
async def refresh(**kwargs):
return None
@@ -235,10 +229,9 @@ async def test_batch_partial_failure_refreshes_successful_files_and_retry_is_saf
root = "viking://resources/wiki"
a = f"{root}/a.md"
b = f"{root}/b.md"
- locks = _LockManager()
vfs = _VFS(root, fail_uri=b)
+ locks = vfs._async_agfs
coordinator = ContentWriteCoordinator(vfs)
- monkeypatch.setattr(content_write_module, "get_lock_manager", lambda: locks)
calls = []
async def refresh(**kwargs):
@@ -270,10 +263,8 @@ async def test_batch_partial_failure_refreshes_successful_files_and_retry_is_saf
async def test_batch_refresh_failure_retry_skips_landed_write_and_refreshes(monkeypatch):
root = "viking://resources/wiki"
page = f"{root}/page.md"
- locks = _LockManager()
vfs = _VFS(root)
coordinator = ContentWriteCoordinator(vfs)
- monkeypatch.setattr(content_write_module, "get_lock_manager", lambda: locks)
calls = []
async def refresh(**kwargs):
diff --git a/tests/server/test_content_write_service.py b/tests/server/test_content_write_service.py
index 32a4f9735..0a7949154 100644
--- a/tests/server/test_content_write_service.py
+++ b/tests/server/test_content_write_service.py
@@ -3,13 +3,15 @@
"""Service-level tests for content write coordination."""
+from types import SimpleNamespace
+
import pytest
from openviking.server.identity import RequestContext, Role
from openviking.session.memory.dataclass import MemoryFile
from openviking.session.memory.utils import MemoryFileUtils
from openviking.storage.content_write import ContentWriteCoordinator
-from openviking.storage.errors import ResourceBusyError
+from openviking.storage.errors import LockAcquisitionError, ResourceBusyError
from openviking_cli.exceptions import (
AlreadyExistsError,
DeadlineExceededError,
@@ -288,36 +290,25 @@ async def test_memory_rm_refreshes_nested_schema_overview(service):
assert "[越前龙马-keep-test](./越前龙马-keep-test.md)" in after
-class _FakeHandle:
- def __init__(self, handle_id: str):
- self.id = handle_id
-
+class _FakePathLock:
+ """Mock for _async_agfs pathlock operations."""
-class _FakeLockManager:
- def __init__(
- self,
- *,
- acquire_exact_path_result: bool = True,
- acquire_tree_result: bool = True,
- ):
- self.handle = _FakeHandle("lock-1")
- self.acquire_exact_path_result = acquire_exact_path_result
- self.acquire_tree_result = acquire_tree_result
+ def __init__(self, *, acquire_result=True, acquire_error=None):
+ self._lease = SimpleNamespace(id="lock-1")
+ self.acquire_result = acquire_result
+ self.acquire_error = acquire_error
self.release_calls = []
- def create_handle(self):
- return self.handle
-
- async def acquire_tree(self, handle, path):
- del handle, path
- return self.acquire_tree_result
-
- async def acquire_exact_path(self, handle, path):
- del handle, path
- return self.acquire_exact_path_result
+ async def pathlock_acquire_exact(self, lock_path):
+ del lock_path
+ if self.acquire_error is not None:
+ raise self.acquire_error
+ if not self.acquire_result:
+ raise LockAcquisitionError("lock conflict")
+ return self._lease
- async def release(self, handle):
- self.release_calls.append(handle.id)
+ async def pathlock_release(self, lease):
+ self.release_calls.append(lease.id)
class _FakeVikingFS:
@@ -330,6 +321,7 @@ class _FakeVikingFS:
self.content = {file_uri: "original"}
self.vector_store = None
self.tree_entries = []
+ self._async_agfs = _FakePathLock()
async def stat(self, uri: str, ctx=None):
del ctx
@@ -354,13 +346,13 @@ class _FakeVikingFS:
del ctx
return self.content[uri]
- async def write_file(self, uri: str, content: str, ctx=None, lock_handle=None):
+ async def write_file(self, uri: str, content: str, ctx=None, lock_handle=None, lease_ref=None):
del ctx
- self.write_file_calls.append((uri, content, lock_handle))
+ self.write_file_calls.append((uri, content, lease_ref or lock_handle))
self.content[uri] = content
- async def rm(self, uri: str, ctx=None, lock_handle=None):
- del ctx, lock_handle
+ async def rm(self, uri: str, ctx=None, lock_handle=None, lease_ref=None):
+ del ctx, lock_handle, lease_ref
self.rm_calls.append(uri)
self.content.pop(uri, None)
@@ -439,12 +431,6 @@ async def test_write_timeout_after_enqueue_releases_resource_lock(monkeypatch):
ctx = RequestContext(user=UserIdentifier.the_default_user(), role=Role.USER)
viking_fs = _FakeVikingFS(file_uri=file_uri, root_uri=root_uri)
coordinator = ContentWriteCoordinator(viking_fs=viking_fs)
- lock_manager = _FakeLockManager()
-
- monkeypatch.setattr(
- "openviking.storage.content_write.get_lock_manager",
- lambda: lock_manager,
- )
async def _fake_enqueue_semantic_refresh(**kwargs):
del kwargs
@@ -465,7 +451,7 @@ async def test_write_timeout_after_enqueue_releases_resource_lock(monkeypatch):
wait=True,
)
- assert lock_manager.release_calls == ["lock-1"]
+ assert viking_fs._async_agfs.release_calls == ["lock-1"]
assert viking_fs.delete_temp_calls == []
assert viking_fs.content[file_uri] == "updated"
@@ -476,13 +462,8 @@ async def test_resource_write_lock_conflict_raises_resource_busy(monkeypatch):
root_uri = "viking://resources/demo"
ctx = RequestContext(user=UserIdentifier.the_default_user(), role=Role.USER)
viking_fs = _FakeVikingFS(file_uri=file_uri, root_uri=root_uri)
+ viking_fs._async_agfs = _FakePathLock(acquire_result=False)
coordinator = ContentWriteCoordinator(viking_fs=viking_fs)
- lock_manager = _FakeLockManager(acquire_exact_path_result=False)
-
- monkeypatch.setattr(
- "openviking.storage.content_write.get_lock_manager",
- lambda: lock_manager,
- )
with pytest.raises(ResourceBusyError) as exc_info:
await coordinator.write(
@@ -492,7 +473,7 @@ async def test_resource_write_lock_conflict_raises_resource_busy(monkeypatch):
)
assert exc_info.value.uri == file_uri
- assert lock_manager.release_calls == ["lock-1"]
+ assert viking_fs._async_agfs.release_calls == []
assert viking_fs.content[file_uri] == "original"
@@ -502,13 +483,8 @@ async def test_memory_write_lock_conflict_raises_resource_busy(monkeypatch):
root_uri = "viking://user/default/memories/preferences"
ctx = RequestContext(user=UserIdentifier.the_default_user(), role=Role.USER)
viking_fs = _FakeVikingFS(file_uri=file_uri, root_uri=root_uri)
+ viking_fs._async_agfs = _FakePathLock(acquire_result=False)
coordinator = ContentWriteCoordinator(viking_fs=viking_fs)
- lock_manager = _FakeLockManager(acquire_exact_path_result=False)
-
- monkeypatch.setattr(
- "openviking.storage.content_write.get_lock_manager",
- lambda: lock_manager,
- )
with pytest.raises(ResourceBusyError) as exc_info:
await coordinator.write(
@@ -518,27 +494,46 @@ async def test_memory_write_lock_conflict_raises_resource_busy(monkeypatch):
)
assert exc_info.value.uri == file_uri
- assert lock_manager.release_calls == ["lock-1"]
+ assert viking_fs._async_agfs.release_calls == []
assert viking_fs.content[file_uri] == "original"
@pytest.mark.asyncio
-async def test_write_direct_reuses_outer_lock_handle_for_viking_fs(monkeypatch):
+ "file_uri",
+ [
+ "viking://resources/demo/doc.md",
+ "viking://user/default/memories/preferences/theme.md",
+ ],
+)
+async def test_write_lock_storage_error_is_not_mapped_to_resource_busy(file_uri):
+ """Preserve non-conflict acquisition failures for direct and memory writes."""
+ root_uri = file_uri.rsplit("/", 1)[0]
+ ctx = RequestContext(user=UserIdentifier.the_default_user(), role=Role.USER)
+ viking_fs = _FakeVikingFS(file_uri=file_uri, root_uri=root_uri)
+ viking_fs._async_agfs = _FakePathLock(acquire_error=RuntimeError("storage failed"))
+ coordinator = ContentWriteCoordinator(viking_fs=viking_fs)
+
+ with pytest.raises(RuntimeError, match="storage failed"):
+ await coordinator.write(
+ uri=file_uri,
+ content="updated",
+ ctx=ctx,
+ )
+
+
+async def test_write_direct_reuses_outer_lease_for_viking_fs(monkeypatch):
file_uri = "viking://resources/demo/doc.md"
root_uri = "viking://resources/demo"
ctx = RequestContext(user=UserIdentifier.the_default_user(), role=Role.USER)
viking_fs = _FakeVikingFS(file_uri=file_uri, root_uri=root_uri)
coordinator = ContentWriteCoordinator(viking_fs=viking_fs)
- lock_manager = _FakeLockManager()
async def _fake_enqueue_semantic_refresh(**kwargs):
del kwargs
return None
- monkeypatch.setattr(
- "openviking.storage.content_write.get_lock_manager",
- lambda: lock_manager,
- )
monkeypatch.setattr(coordinator, "_enqueue_semantic_refresh", _fake_enqueue_semantic_refresh)
result = await coordinator._write_direct_with_refresh(
@@ -555,7 +550,8 @@ async def test_write_direct_reuses_outer_lock_handle_for_viking_fs(monkeypatch):
)
assert result["uri"] == file_uri
- assert viking_fs.write_file_calls == [(file_uri, "updated", lock_manager.handle)]
+ assert viking_fs.write_file_calls[0][0:2] == (file_uri, "updated")
+ assert viking_fs.write_file_calls[0][2].id == "lock-1"
@pytest.mark.asyncio
@@ -565,14 +561,8 @@ async def test_resource_write_updates_target_and_queues_refresh_before_return(mo
ctx = RequestContext(user=UserIdentifier.the_default_user(), role=Role.USER)
viking_fs = _FakeVikingFS(file_uri=file_uri, root_uri=root_uri)
coordinator = ContentWriteCoordinator(viking_fs=viking_fs)
- lock_manager = _FakeLockManager()
captured_enqueue = {}
- monkeypatch.setattr(
- "openviking.storage.content_write.get_lock_manager",
- lambda: lock_manager,
- )
-
async def _fake_enqueue_semantic_refresh(**kwargs):
captured_enqueue.update(kwargs)
@@ -594,7 +584,7 @@ async def test_resource_write_updates_target_and_queues_refresh_before_return(mo
assert captured_enqueue["changed_uri"] == file_uri
assert captured_enqueue["change_type"] == "modified"
assert viking_fs.delete_temp_calls == []
- assert lock_manager.release_calls == ["lock-1"]
+ assert viking_fs._async_agfs.release_calls == ["lock-1"]
@pytest.mark.asyncio
@@ -604,12 +594,6 @@ async def test_resource_write_rolls_back_replace_when_enqueue_fails(monkeypatch)
ctx = RequestContext(user=UserIdentifier.the_default_user(), role=Role.USER)
viking_fs = _FakeVikingFS(file_uri=file_uri, root_uri=root_uri)
coordinator = ContentWriteCoordinator(viking_fs=viking_fs)
- lock_manager = _FakeLockManager()
-
- monkeypatch.setattr(
- "openviking.storage.content_write.get_lock_manager",
- lambda: lock_manager,
- )
async def _fail_enqueue(**kwargs):
del kwargs
@@ -626,11 +610,12 @@ async def test_resource_write_rolls_back_replace_when_enqueue_fails(monkeypatch)
)
assert viking_fs.content[file_uri] == "original"
- assert viking_fs.write_file_calls == [
- (file_uri, "updated", lock_manager.handle),
- (file_uri, "original", lock_manager.handle),
+ assert [call[0:2] for call in viking_fs.write_file_calls] == [
+ (file_uri, "updated"),
+ (file_uri, "original"),
]
- assert lock_manager.release_calls == ["lock-1"]
+ assert [call[2].id for call in viking_fs.write_file_calls] == ["lock-1", "lock-1"]
+ assert viking_fs._async_agfs.release_calls == ["lock-1"]
@pytest.mark.asyncio
@@ -640,12 +625,6 @@ async def test_resource_write_rolls_back_create_when_enqueue_fails(monkeypatch):
ctx = RequestContext(user=UserIdentifier.the_default_user(), role=Role.USER)
viking_fs = _FakeVikingFSForCreate(file_uri=file_uri, root_uri=root_uri, file_exists=False)
coordinator = ContentWriteCoordinator(viking_fs=viking_fs)
- lock_manager = _FakeLockManager()
-
- monkeypatch.setattr(
- "openviking.storage.content_write.get_lock_manager",
- lambda: lock_manager,
- )
async def _fail_enqueue(**kwargs):
del kwargs
@@ -663,7 +642,7 @@ async def test_resource_write_rolls_back_create_when_enqueue_fails(monkeypatch):
assert file_uri not in viking_fs.content
assert viking_fs.rm_calls == [file_uri]
- assert lock_manager.release_calls == ["lock-1"]
+ assert viking_fs._async_agfs.release_calls == ["lock-1"]
@pytest.mark.asyncio
@@ -673,15 +652,9 @@ async def test_memory_write_wait_skips_semantic_queue_and_releases_write_lock(mo
ctx = RequestContext(user=UserIdentifier.the_default_user(), role=Role.USER)
viking_fs = _FakeVikingFS(file_uri=file_uri, root_uri=root_uri)
coordinator = ContentWriteCoordinator(viking_fs=viking_fs)
- lock_manager = _FakeLockManager()
-
- monkeypatch.setattr(
- "openviking.storage.content_write.get_lock_manager",
- lambda: lock_manager,
- )
- async def _fake_write_in_place(uri, content, *, mode, ctx, lock_handle=None):
- del uri, content, mode, ctx, lock_handle
+ async def _fake_write_in_place(uri, content, *, mode, ctx, lock_handle=None, lease_ref=None):
+ del uri, content, mode, ctx, lock_handle, lease_ref
return None
async def _fail_wait_for_request(*, telemetry_id, timeout):
@@ -706,7 +679,7 @@ async def test_memory_write_wait_skips_semantic_queue_and_releases_write_lock(mo
wait=True,
)
- assert lock_manager.release_calls == ["lock-1"]
+ assert viking_fs._async_agfs.release_calls == ["lock-1"]
assert result["semantic_status"] == "skipped"
assert result["vector_status"] == "skipped"
assert result["overview_status"] == "complete"
@@ -734,6 +707,7 @@ class _FakeVikingFSForCreate:
self.rm_calls = []
self.content = {}
self.existing_dirs = set({root_uri} if existing_dirs is None else existing_dirs)
+ self._async_agfs = _FakePathLock()
async def stat(self, uri: str, ctx=None):
del ctx
@@ -759,9 +733,17 @@ class _FakeVikingFSForCreate:
del ctx
self.delete_temp_calls.append(temp_uri)
- async def write_file(self, uri: str, content: str, *, ctx=None, lock_handle=None):
+ async def write_file(
+ self,
+ uri: str,
+ content: str,
+ *,
+ ctx=None,
+ lock_handle=None,
+ lease_ref=None,
+ ):
del ctx
- self.write_file_calls.append((uri, content, lock_handle))
+ self.write_file_calls.append((uri, content, lease_ref or lock_handle))
self.content[uri] = content
parent = uri.rsplit("/", 1)[0]
while parent.startswith("viking://") and parent not in self.existing_dirs:
@@ -770,8 +752,8 @@ class _FakeVikingFSForCreate:
break
parent = parent.rsplit("/", 1)[0]
- async def rm(self, uri: str, *, ctx=None, lock_handle=None):
- del ctx, lock_handle
+ async def rm(self, uri: str, *, ctx=None, lock_handle=None, lease_ref=None):
+ del ctx, lock_handle, lease_ref
self.rm_calls.append(uri)
self.content.pop(uri, None)
@@ -786,14 +768,11 @@ async def test_create_mode_new_file_success(monkeypatch):
ctx = RequestContext(user=UserIdentifier.the_default_user(), role=Role.USER)
viking_fs = _FakeVikingFSForCreate(file_uri=file_uri, root_uri=root_uri, file_exists=False)
coordinator = ContentWriteCoordinator(viking_fs=viking_fs)
- lock_manager = _FakeLockManager()
-
- monkeypatch.setattr("openviking.storage.content_write.get_lock_manager", lambda: lock_manager)
write_calls = []
- async def _fake_write_in_place(uri, content, *, mode, ctx, lock_handle=None):
- del mode, ctx, lock_handle
+ async def _fake_write_in_place(uri, content, *, mode, ctx, lock_handle=None, lease_ref=None):
+ del mode, ctx, lock_handle, lease_ref
write_calls.append((uri, content))
return content
@@ -824,15 +803,12 @@ async def test_create_mode_canonicalizes_user_shorthand_memory_uri(monkeypatch):
file_exists=False,
)
coordinator = ContentWriteCoordinator(viking_fs=viking_fs)
- lock_manager = _FakeLockManager()
-
- monkeypatch.setattr("openviking.storage.content_write.get_lock_manager", lambda: lock_manager)
write_calls = []
refresh_calls = []
- async def _fake_write_in_place(uri, content, *, mode, ctx, lock_handle=None):
- del mode, ctx, lock_handle
+ async def _fake_write_in_place(uri, content, *, mode, ctx, lock_handle=None, lease_ref=None):
+ del mode, ctx, lock_handle, lease_ref
write_calls.append((uri, content))
return content
@@ -870,8 +846,8 @@ async def test_create_mode_existing_file_raises_409(monkeypatch):
viking_fs = _FakeVikingFSForCreate(file_uri=file_uri, root_uri=root_uri, file_exists=True)
coordinator = ContentWriteCoordinator(viking_fs=viking_fs)
- async def _fake_write_in_place(uri, content, *, mode, ctx, lock_handle=None):
- del uri, content, mode, ctx, lock_handle
+ async def _fake_write_in_place(uri, content, *, mode, ctx, lock_handle=None, lease_ref=None):
+ del uri, content, mode, ctx, lock_handle, lease_ref
return None
async def _fake_wait_for_queues(*, timeout):
@@ -893,8 +869,8 @@ async def test_create_mode_invalid_extension_raises_400(monkeypatch):
viking_fs = _FakeVikingFSForCreate(file_uri=file_uri, root_uri=root_uri, file_exists=False)
coordinator = ContentWriteCoordinator(viking_fs=viking_fs)
- async def _fake_write_in_place(uri, content, *, mode, ctx, lock_handle=None):
- del uri, content, mode, ctx, lock_handle
+ async def _fake_write_in_place(uri, content, *, mode, ctx, lock_handle=None, lease_ref=None):
+ del uri, content, mode, ctx, lock_handle, lease_ref
return None
async def _fake_wait_for_queues(*, timeout):
@@ -915,14 +891,11 @@ async def test_create_mode_parent_dirs_auto_created(monkeypatch):
ctx = RequestContext(user=UserIdentifier.the_default_user(), role=Role.USER)
viking_fs = _FakeVikingFSForCreate(file_uri=file_uri, root_uri=root_uri, file_exists=False)
coordinator = ContentWriteCoordinator(viking_fs=viking_fs)
- lock_manager = _FakeLockManager()
-
- monkeypatch.setattr("openviking.storage.content_write.get_lock_manager", lambda: lock_manager)
write_calls = []
- async def _fake_write_in_place(uri, content, *, mode, ctx, lock_handle=None):
- del mode, ctx, lock_handle
+ async def _fake_write_in_place(uri, content, *, mode, ctx, lock_handle=None, lease_ref=None):
+ del mode, ctx, lock_handle, lease_ref
write_calls.append((uri, content))
return content
@@ -953,16 +926,11 @@ async def test_create_mode_valid_extensions_pass(monkeypatch):
root_uri = "viking://user/default/memories"
viking_fs = _FakeVikingFSForCreate(file_uri=file_uri, root_uri=root_uri, file_exists=False)
coordinator = ContentWriteCoordinator(viking_fs=viking_fs)
- lock_manager = _FakeLockManager()
- _captured_lock = lock_manager
-
- monkeypatch.setattr(
- "openviking.storage.content_write.get_lock_manager", lambda _l=_captured_lock: _l
- )
-
- async def _fake_write_in_place(uri, content, *, mode, ctx, lock_handle=None):
- del uri, mode, ctx, lock_handle
+ async def _fake_write_in_place(
+ uri, content, *, mode, ctx, lock_handle=None, lease_ref=None
+ ):
+ del uri, mode, ctx, lock_handle, lease_ref
return content
async def _fake_wait_for_queues(*, timeout):
@@ -985,12 +953,9 @@ async def test_create_mode_memory_scope(monkeypatch):
ctx = RequestContext(user=UserIdentifier.the_default_user(), role=Role.USER)
viking_fs = _FakeVikingFSForCreate(file_uri=file_uri, root_uri=root_uri, file_exists=False)
coordinator = ContentWriteCoordinator(viking_fs=viking_fs)
- lock_manager = _FakeLockManager()
-
- monkeypatch.setattr("openviking.storage.content_write.get_lock_manager", lambda: lock_manager)
- async def _fake_write_in_place(uri, content, *, mode, ctx, lock_handle=None):
- del uri, mode, ctx, lock_handle
+ async def _fake_write_in_place(uri, content, *, mode, ctx, lock_handle=None, lease_ref=None):
+ del uri, mode, ctx, lock_handle, lease_ref
return content
refresh_calls = []
@@ -1024,9 +989,6 @@ async def test_create_mode_resource_scope(monkeypatch):
ctx = RequestContext(user=UserIdentifier.the_default_user(), role=Role.USER)
viking_fs = _FakeVikingFSForCreate(file_uri=file_uri, root_uri=root_uri, file_exists=False)
coordinator = ContentWriteCoordinator(viking_fs=viking_fs)
- lock_manager = _FakeLockManager()
-
- monkeypatch.setattr("openviking.storage.content_write.get_lock_manager", lambda: lock_manager)
async def _fake_enqueue_semantic_refresh(**kwargs):
# Verify resource-scope URIs take the resource write path
@@ -1106,14 +1068,11 @@ async def test_create_mode_regression_replace_unchanged(monkeypatch):
ctx = RequestContext(user=UserIdentifier.the_default_user(), role=Role.USER)
viking_fs = _FakeVikingFSForCreate(file_uri=file_uri, root_uri=root_uri, file_exists=True)
coordinator = ContentWriteCoordinator(viking_fs=viking_fs)
- lock_manager = _FakeLockManager()
-
- monkeypatch.setattr("openviking.storage.content_write.get_lock_manager", lambda: lock_manager)
- async def _fake_write_in_place(uri, content, *, mode, ctx, lock_handle=None):
+ async def _fake_write_in_place(uri, content, *, mode, ctx, lock_handle=None, lease_ref=None):
# Verify mode="replace" still works
assert mode == "replace"
- del uri, content, ctx, lock_handle
+ del uri, content, ctx, lock_handle, lease_ref
return None
async def _fake_wait_for_queues(*, timeout):
@@ -1137,14 +1096,11 @@ async def test_create_mode_regression_append_unchanged(monkeypatch):
ctx = RequestContext(user=UserIdentifier.the_default_user(), role=Role.USER)
viking_fs = _FakeVikingFSForCreate(file_uri=file_uri, root_uri=root_uri, file_exists=True)
coordinator = ContentWriteCoordinator(viking_fs=viking_fs)
- lock_manager = _FakeLockManager()
-
- monkeypatch.setattr("openviking.storage.content_write.get_lock_manager", lambda: lock_manager)
- async def _fake_write_in_place(uri, content, *, mode, ctx, lock_handle=None):
+ async def _fake_write_in_place(uri, content, *, mode, ctx, lock_handle=None, lease_ref=None):
# Verify mode="append" still works
assert mode == "append"
- del uri, content, ctx, lock_handle
+ del uri, content, ctx, lock_handle, lease_ref
return None
async def _fake_wait_for_queues(*, timeout):
diff --git a/tests/server/test_request_wait_tracking.py b/tests/server/test_request_wait_tracking.py
index 3309da21d..d654e1de6 100644
--- a/tests/server/test_request_wait_tracking.py
+++ b/tests/server/test_request_wait_tracking.py
@@ -47,6 +47,10 @@ class _FakeVikingFS:
self._file_uri = file_uri
self._root_uri = root_uri
self.content = {file_uri: "original"}
+ self._async_agfs = SimpleNamespace(
+ pathlock_acquire_exact=lambda lock_path: SimpleNamespace(id="lock-1"),
+ pathlock_release=lambda lease: None,
+ )
async def stat(self, uri: str, ctx=None):
del ctx
@@ -68,12 +72,12 @@ class _FakeVikingFS:
del ctx
return self.content[uri]
- async def write_file(self, uri: str, content: str, ctx=None):
- del ctx
+ async def write_file(self, uri: str, content: str, ctx=None, lease_ref=None):
+ del ctx, lease_ref
self.content[uri] = content
- async def rm(self, uri: str, ctx=None, lock_handle=None):
- del ctx, lock_handle
+ async def rm(self, uri: str, ctx=None, lock_handle=None, lease_ref=None):
+ del ctx, lock_handle, lease_ref
self.content.pop(uri, None)
@@ -263,16 +267,7 @@ async def test_content_write_wait_uses_request_tracker(monkeypatch):
coordinator = ContentWriteCoordinator(
viking_fs=_FakeVikingFS(file_uri=file_uri, root_uri=root_uri)
)
- lock_manager = SimpleNamespace(
- create_handle=lambda: SimpleNamespace(id="lock-1"),
- acquire_exact_path=lambda handle, path: _return_true(handle, path),
- release=lambda handle: _return_none(handle),
- )
- monkeypatch.setattr(
- "openviking.storage.content_write.get_lock_manager",
- lambda: lock_manager,
- )
monkeypatch.setattr(
"openviking.storage.content_write.get_request_wait_tracker",
lambda: tracker,
@@ -323,16 +318,7 @@ async def test_content_write_wait_uses_request_tracker_when_telemetry_disabled(m
coordinator = ContentWriteCoordinator(
viking_fs=_FakeVikingFS(file_uri=file_uri, root_uri=root_uri)
)
- lock_manager = SimpleNamespace(
- create_handle=lambda: SimpleNamespace(id="lock-1"),
- acquire_exact_path=lambda handle, path: _return_true(handle, path),
- release=lambda handle: _return_none(handle),
- )
- monkeypatch.setattr(
- "openviking.storage.content_write.get_lock_manager",
- lambda: lock_manager,
- )
monkeypatch.setattr(
"openviking.storage.content_write.get_request_wait_tracker",
lambda: tracker,
diff --git a/tests/service/test_reindex_file_lock.py b/tests/service/test_reindex_file_lock.py
index 8ca48f7cb..bd568f7bf 100644
--- a/tests/service/test_reindex_file_lock.py
+++ b/tests/service/test_reindex_file_lock.py
@@ -8,7 +8,6 @@ from unittest.mock import AsyncMock
from openviking.server.identity import RequestContext, Role
from openviking.service import reindex_executor as reindex_module
from openviking.service.reindex_executor import ReindexExecutor
-from openviking.storage.transaction import init_lock_manager, release_all_locks, reset_lock_manager
from openviking_cli.session.user_id import UserIdentifier
@@ -39,7 +38,6 @@ async def test_reindex_single_file_uri_acquires_tree_lock_without_not_a_director
uri = "viking://resources/profile.md"
path = f"{test_dir}/profile.md"
agfs_client.write(path, b"# Profile\nSingle file reindex source.\n")
- init_lock_manager(agfs_client)
viking_fs = _FakeVikingFS(uri, path)
service = SimpleNamespace(
@@ -65,8 +63,7 @@ async def test_reindex_single_file_uri_acquires_tree_lock_without_not_a_director
ctx=ctx,
)
finally:
- await release_all_locks()
- reset_lock_manager()
+ pass
assert result["status"] == "completed"
assert result["uri"] == uri
diff --git a/tests/service/test_resource_service_understanding_routing.py b/tests/service/test_resource_service_understanding_routing.py
index 25ccbfe96..b352b6f81 100644
--- a/tests/service/test_resource_service_understanding_routing.py
+++ b/tests/service/test_resource_service_understanding_routing.py
@@ -14,6 +14,7 @@ from openviking_cli.session.user_id import UserIdentifier
def mpeg_ts_probe() -> bytes:
+ """Build a minimal MPEG-TS probe payload for routing tests."""
content = bytearray(MPEG_TS_PROBE_BYTES)
for offset in range(0, MPEG_TS_PROBE_BYTES, MPEG_TS_PACKET_SIZE):
content[offset] = 0x47
@@ -25,6 +26,7 @@ async def test_extensionless_remote_url_queues_frozen_understanding_route(
monkeypatch,
tmp_path,
):
+ """Queue understanding ingestion for extensionless remote URLs after prepare."""
ctx = RequestContext(
user=UserIdentifier("acct", "alice"),
role=Role.USER,
@@ -42,10 +44,11 @@ async def test_extensionless_remote_url_queues_frozen_understanding_route(
},
is_temporary=True,
)
- lock = SimpleNamespace(
- to_handoff=lambda: SimpleNamespace(to_dict=lambda: {"handle_id": "lock-1"}),
- handoff=AsyncMock(),
- close=AsyncMock(),
+ lock = {"lease_ref": "lock-1"}
+ agfs = SimpleNamespace(
+ pathlock_to_handoff=AsyncMock(return_value={"handle_id": "lock-1"}),
+ pathlock_handoff=AsyncMock(),
+ pathlock_release=AsyncMock(),
)
processor = SimpleNamespace(
understanding_api_enabled=lambda: True,
@@ -66,7 +69,7 @@ async def test_extensionless_remote_url_queues_frozen_understanding_route(
)
service = ResourceService(
vikingdb=object(),
- viking_fs=object(),
+ viking_fs=SimpleNamespace(_async_agfs=agfs),
resource_processor=processor,
skill_processor=object(),
)
@@ -86,10 +89,6 @@ async def test_extensionless_remote_url_queues_frozen_understanding_route(
"openviking.storage.queuefs.get_queue_manager",
lambda: queue_manager,
)
- monkeypatch.setattr(
- "openviking.storage.transaction.get_lock_manager",
- lambda: object(),
- )
result = await service.add_resource(
path="https://example.com/download?id=1",
@@ -114,7 +113,8 @@ async def test_extensionless_remote_url_queues_frozen_understanding_route(
assert not downloaded.exists()
processor.submit_understanding.assert_awaited_once_with(prepared)
processor.process_resource.assert_not_awaited()
- lock.handoff.assert_awaited_once()
+ agfs.pathlock_to_handoff.assert_awaited_once_with(lock)
+ agfs.pathlock_handoff.assert_awaited_once_with(lock)
@pytest.mark.asyncio
@@ -122,6 +122,7 @@ async def test_remote_mpeg_ts_url_queues_understanding_after_prepare(
monkeypatch,
tmp_path,
):
+ """Route MPEG-TS resources to understanding with video target resolution."""
ctx = RequestContext(
user=UserIdentifier("acct", "alice"),
role=Role.USER,
@@ -139,10 +140,11 @@ async def test_remote_mpeg_ts_url_queues_understanding_after_prepare(
},
is_temporary=True,
)
- lock = SimpleNamespace(
- to_handoff=lambda: SimpleNamespace(to_dict=lambda: {"handle_id": "lock-1"}),
- handoff=AsyncMock(),
- close=AsyncMock(),
+ lock = {"lease_ref": "lock-1"}
+ agfs = SimpleNamespace(
+ pathlock_to_handoff=AsyncMock(return_value={"handle_id": "lock-1"}),
+ pathlock_handoff=AsyncMock(),
+ pathlock_release=AsyncMock(),
)
resolve_target_uri = AsyncMock(
return_value=(
@@ -164,7 +166,7 @@ async def test_remote_mpeg_ts_url_queues_understanding_after_prepare(
)
service = ResourceService(
vikingdb=object(),
- viking_fs=object(),
+ viking_fs=SimpleNamespace(_async_agfs=agfs),
resource_processor=processor,
skill_processor=object(),
)
@@ -184,10 +186,6 @@ async def test_remote_mpeg_ts_url_queues_understanding_after_prepare(
"openviking.storage.queuefs.get_queue_manager",
lambda: queue_manager,
)
- monkeypatch.setattr(
- "openviking.storage.transaction.get_lock_manager",
- lambda: object(),
- )
result = await service.add_resource(
path="https://example.com/video/sample.ts?sign=1",
@@ -214,4 +212,5 @@ async def test_remote_mpeg_ts_url_queues_understanding_after_prepare(
assert queued.understanding_response_id == "response-1"
assert queued.source_name == "sample.ts"
assert not downloaded.exists()
- lock.handoff.assert_awaited_once()
+ agfs.pathlock_to_handoff.assert_awaited_once_with(lock)
+ agfs.pathlock_handoff.assert_awaited_once_with(lock)
diff --git a/tests/service/test_resource_service_watch.py b/tests/service/test_resource_service_watch.py
index ea555d84c..b12295753 100644
--- a/tests/service/test_resource_service_watch.py
+++ b/tests/service/test_resource_service_watch.py
@@ -835,6 +835,9 @@ class TestResourceProcessingIndependence:
skill_processor=MockSkillProcessor(),
watch_scheduler=scheduler,
)
+ service._enqueue_add_resource_job = AsyncMock(
+ return_value=SimpleNamespace(task_id="test-task")
+ )
result = await service.add_resource(
path="/test/path",
@@ -856,6 +859,9 @@ class TestResourceProcessingIndependence:
skill_processor=MockSkillProcessor(),
watch_scheduler=None,
)
+ service._enqueue_add_resource_job = AsyncMock(
+ return_value=SimpleNamespace(task_id="test-task")
+ )
result = await service.add_resource(
path="/test/path",
diff --git a/tests/session/memory/test_compressor_v2.py b/tests/session/memory/test_compressor_v2.py
index c17f0e9dd..522327bab 100644
--- a/tests/session/memory/test_compressor_v2.py
+++ b/tests/session/memory/test_compressor_v2.py
@@ -477,8 +477,6 @@ class TestCompressorV2:
with (
patch("openviking.storage.viking_fs.get_viking_fs", return_value=None),
- patch("openviking.storage.transaction.init_lock_manager"),
- patch("openviking.storage.transaction.get_lock_manager", return_value=None),
patch(
"openviking.session.memory.memory_type_registry.create_default_registry",
return_value=dummy_registry,
@@ -513,8 +511,6 @@ class TestCompressorV2:
with (
patch("openviking.storage.viking_fs.get_viking_fs", return_value=None),
- patch("openviking.storage.transaction.init_lock_manager"),
- patch("openviking.storage.transaction.get_lock_manager", return_value=None),
patch(
"openviking.session.memory.memory_type_registry.create_default_registry",
return_value=dummy_registry,
@@ -586,8 +582,6 @@ class TestCompressorV2:
with (
patch("openviking.session.compressor_v2.get_viking_fs", return_value=MockVikingFS()),
- patch("openviking.storage.transaction.init_lock_manager"),
- patch("openviking.storage.transaction.get_lock_manager", return_value=lock_manager),
patch(
"openviking.session.memory.memory_type_registry.create_default_registry",
return_value=SimpleNamespace(initialize_memory_files=AsyncMock()),
@@ -682,12 +676,6 @@ class TestCompressorV2:
async def release(_handle):
events.append("release")
- lock_manager = SimpleNamespace(
- create_handle=lambda: handle,
- acquire_exact_tree_batch=AsyncMock(side_effect=acquire_exact_tree_batch),
- release=AsyncMock(side_effect=release),
- )
-
async def post_apply(result, inheritance_map, lock_handle):
assert result.written_uris == ["viking://user/default/memories/experiences/debug.md"]
assert inheritance_map == {}
@@ -698,8 +686,6 @@ class TestCompressorV2:
patch("openviking.session.compressor_v2.get_viking_fs", return_value=FakeVikingFS()),
patch("openviking.session.compressor_v2.get_openviking_config", return_value=config),
patch("openviking.session.compressor_v2.ExtractLoop", DummyExtractLoop),
- patch("openviking.storage.transaction.init_lock_manager"),
- patch("openviking.storage.transaction.get_lock_manager", return_value=lock_manager),
patch.object(compressor, "_get_or_create_updater", return_value=DummyUpdater()),
):
result = await compressor._run_extract_phase(
@@ -747,8 +733,6 @@ class TestCompressorV2:
events.append("write")
self.files[uri] = content
- handle = SimpleNamespace(id="handle-1", locks=[])
-
async def acquire_exact_path_batch(_handle, paths):
events.append(f"exact:{paths[0]}")
return True
@@ -756,14 +740,9 @@ class TestCompressorV2:
async def release(_handle):
events.append("release")
- lock_manager = SimpleNamespace(
- create_handle=lambda: handle,
- acquire_exact_path_batch=AsyncMock(side_effect=acquire_exact_path_batch),
- release=AsyncMock(side_effect=release),
- )
viking_fs = FakeVikingFS()
- with patch("openviking.storage.transaction.get_lock_manager", return_value=lock_manager):
+ with patch("openviking.session.compressor_v2.get_viking_fs", return_value=viking_fs):
await compressor._append_trajectories_to_experiences(
[exp_uri],
[traj_uri],
diff --git a/tests/session/memory/test_memory_updater.py b/tests/session/memory/test_memory_updater.py
index 62cef1c13..a1217a21b 100644
--- a/tests/session/memory/test_memory_updater.py
+++ b/tests/session/memory/test_memory_updater.py
@@ -174,7 +174,6 @@ class TestMemoryUpdater:
@pytest.mark.asyncio
async def test_generate_overview_deletes_empty_overview_via_rm(self):
- lock_handle = object()
schema = MemoryTypeSchema(
memory_type="entities",
description="entity memory",
@@ -193,11 +192,11 @@ class TestMemoryUpdater:
async def ls(self, uri, show_all_hidden=False, ctx=None):
return [{"name": ".overview.md", "isDir": False}]
- async def rm(self, uri, recursive=False, ctx=None, lock_handle=None):
- self.rm_calls.append((uri, recursive, lock_handle))
+ async def rm(self, uri, recursive=False, ctx=None):
+ self.rm_calls.append((uri, recursive))
viking_fs = FakeVikingFS()
- updater = MemoryUpdater(registry=registry, transaction_handle=lock_handle)
+ updater = MemoryUpdater(registry=registry)
updater._get_viking_fs = MagicMock(return_value=viking_fs)
ctx = RequestContext(user=UserIdentifier("acme", "alice"), role=Role.USER)
@@ -211,9 +210,8 @@ class TestMemoryUpdater:
(
"viking://user/alice/memories/entities/动漫角色/.overview.md",
False,
- lock_handle,
),
- ("viking://user/alice/memories/entities/动漫角色", True, lock_handle),
+ ("viking://user/alice/memories/entities/动漫角色", True),
]
@pytest.mark.asyncio
@@ -236,7 +234,7 @@ class TestMemoryUpdater:
async def ls(self, uri, show_all_hidden=False, ctx=None):
raise NotFoundError(uri, "directory")
- async def rm(self, uri, recursive=False, ctx=None, lock_handle=None):
+ async def rm(self, uri, recursive=False, ctx=None):
self.rm_calls.append((uri, recursive))
viking_fs = FakeVikingFS()
@@ -308,7 +306,7 @@ class TestMemoryUpdater:
async def read_file(self, uri, ctx=None):
return self.store[uri]
- async def write_file(self, uri, content, ctx=None, lock_handle=None):
+ async def write_file(self, uri, content, ctx=None):
self.store[uri] = content
viking_fs = FakeVikingFS()
@@ -353,7 +351,7 @@ class TestMemoryUpdater:
async def read_file(self, uri, ctx=None):
return self.store[uri]
- async def write_file(self, uri, content, ctx=None, lock_handle=None):
+ async def write_file(self, uri, content, ctx=None):
self.store[uri] = content
viking_fs = FakeVikingFS()
@@ -467,8 +465,7 @@ class TestMemoryUpdater:
assert error_target == "events(page_id=102)"
assert str(error) == "Missing resolved URI"
tracer_error.assert_called_once_with(
- "Skipping unresolved memory operation: "
- "events(page_id=102): Missing resolved URI"
+ "Skipping unresolved memory operation: events(page_id=102): Missing resolved URI"
)
@pytest.mark.asyncio
@@ -510,9 +507,7 @@ class TestMemoryUpdater:
page_id=102,
),
],
- delete_file_contents=[
- MemoryFile(uri=old_uri, extra_fields={"memory_type": "events"})
- ],
+ delete_file_contents=[MemoryFile(uri=old_uri, extra_fields={"memory_type": "events"})],
errors=[],
)
ctx = RequestContext(user=UserIdentifier("acme", "alice"), role=Role.USER)
@@ -1084,18 +1079,14 @@ class TestApplyEditWithSearchReplacePatch:
@pytest.mark.asyncio
async def test_apply_upsert_persists_last_update_trace_id(self):
- lock_handle = object()
updater = self._make_updater_with_registry()
- updater._transaction_handle = lock_handle
mock_viking_fs = MagicMock()
mock_viking_fs.read_file = AsyncMock(side_effect=FileNotFoundError("missing"))
written_content = None
- write_kwargs = None
async def mock_write_file(uri, content, **kwargs):
- nonlocal write_kwargs, written_content
+ nonlocal written_content
written_content = content
- write_kwargs = kwargs
mock_viking_fs.write_file = mock_write_file
updater._get_viking_fs = MagicMock(return_value=mock_viking_fs)
@@ -1109,7 +1100,6 @@ class TestApplyEditWithSearchReplacePatch:
await updater._apply_upsert(op, MagicMock())
assert written_content is not None
- assert write_kwargs["lock_handle"] is lock_handle
result = MemoryFileUtils.read(written_content)
assert result.extra_fields["source_extraction_id"] == "extract_1"
assert result.extra_fields["last_update_trace_id"] == "trace_1"
diff --git a/tests/session/test_session_commit.py b/tests/session/test_session_commit.py
index 04ed3b851..90d8ce8a5 100644
--- a/tests/session/test_session_commit.py
+++ b/tests/session/test_session_commit.py
@@ -8,14 +8,11 @@ import json
from types import SimpleNamespace
from unittest.mock import AsyncMock, MagicMock
-import pytest
-
from openviking import AsyncOpenViking
from openviking.client.session import Session as ClientSession
from openviking.message import TextPart
from openviking.service.task_tracker import get_task_tracker
from openviking.session import Session
-from openviking.storage.transaction import get_lock_manager
async def _wait_for_task(task_id: str, timeout: float = 30.0) -> dict:
@@ -689,20 +686,3 @@ class TestCommit:
session.add_message("user", [TextPart("Second round message")])
second = await session.commit_async()
assert second["status"] == "accepted"
-
- async def test_commit_skips_redo_when_recovery_disabled(
- self, session_with_messages: Session, monkeypatch: pytest.MonkeyPatch
- ):
- """Phase 2 should not write or clear redo markers when redo recovery is disabled."""
-
- redo_log = MagicMock()
- lock_manager = get_lock_manager()
- monkeypatch.setattr(lock_manager, "_redo_recovery_enabled", False)
- monkeypatch.setattr(lock_manager, "_redo_log", redo_log)
-
- result = await session_with_messages.commit_async()
- task_result = await _wait_for_task(result["task_id"])
-
- assert task_result["status"] == "completed"
- redo_log.write_pending.assert_not_called()
- redo_log.mark_done.assert_not_called()
diff --git a/tests/session/train/test_fakes.py b/tests/session/train/test_fakes.py
index a108f8432..cbcdd09cd 100644
--- a/tests/session/train/test_fakes.py
+++ b/tests/session/train/test_fakes.py
@@ -9,7 +9,7 @@ from typing import Any
class InMemoryAGFS:
- """Tiny synchronous AGFS fake with enough semantics for PathLockEngine."""
+ """Tiny synchronous AGFS fake for training integration tests."""
def __init__(self, files: dict[str, str] | None = None):
self.files: dict[str, bytes] = {}
diff --git a/tests/session/train/test_policy_optimization_real_llm_e2e.py b/tests/session/train/test_policy_optimization_real_llm_e2e.py
index c67ea77cd..53c63465e 100644
--- a/tests/session/train/test_policy_optimization_real_llm_e2e.py
+++ b/tests/session/train/test_policy_optimization_real_llm_e2e.py
@@ -30,7 +30,6 @@ from openviking.session.train import (
TrajectoryRolloutAnalyzer,
)
from openviking.session.train.components.gradient_estimator import ExperienceGradientEstimator
-from openviking.storage.transaction import init_lock_manager, reset_lock_manager
from openviking.telemetry import start_current_span, tracer
from openviking.telemetry.tracer import init_tracer_from_server_config
from openviking_cli.utils.config import get_openviking_config
@@ -534,10 +533,11 @@ def _print_iterative_real_llm_summary(
tracer.info("\n".join(lines), console=True)
-def _patch_experience_prefetch(
- monkeypatch, fs: InMemoryVikingFS, experience_uri: str
-) -> None:
+def _patch_experience_prefetch(monkeypatch, fs: InMemoryVikingFS, experience_uri: str) -> None:
+ """Patch experience prefetch so the test reads from the in-memory filesystem."""
+
async def search_files(self, query, search_uris=None, limit=5):
+ del self, query, search_uris, limit
return [experience_uri]
async def read_file(self, uri):
@@ -603,8 +603,6 @@ async def _run_policy_optimization_pipeline_real_config_llm_e2e_writes_updated_e
)
}
)
- reset_lock_manager()
- init_lock_manager(fs.agfs, redo_recovery_enabled=False)
request_context = SimpleNamespace(
user=SimpleNamespace(account_id="default", user_id="u"),
account_id="default",
@@ -673,14 +671,10 @@ async def _run_policy_optimization_pipeline_real_config_llm_e2e_writes_updated_e
assert trajectory_content.strip()
assert gradient.after_file.plain_content().strip()
assert all(epoch.apply_result.errors == [] for epoch in result.epochs)
- written_uris = [
- uri for epoch in result.epochs for uri in epoch.apply_result.written_uris
- ]
+ written_uris = [uri for epoch in result.epochs for uri in epoch.apply_result.written_uris]
assert experience_uri in written_uris
assert result.plan.metadata["optimizer"] == "patch_merge"
- assert any(
- epoch.plan.metadata.get("optimizer") == "patch_merge" for epoch in result.epochs
- )
+ assert any(epoch.plan.metadata.get("optimizer") == "patch_merge" for epoch in result.epochs)
assert len(result.epochs) == 4
assert result.evaluation_passes == []
assert final_evaluation.metadata["score"] > result.metadata["first_score"]
@@ -725,8 +719,6 @@ async def test_experience_gradient_estimator_real_config_llm_generates_gradient(
),
}
)
- reset_lock_manager()
- init_lock_manager(fs.agfs, redo_recovery_enabled=False)
request_context = SimpleNamespace(
user=SimpleNamespace(account_id="default", user_id="u"),
account_id="default",
diff --git a/tests/session/train/test_train_framework.py b/tests/session/train/test_train_framework.py
index c3f09f4af..6b7f4ce62 100644
--- a/tests/session/train/test_train_framework.py
+++ b/tests/session/train/test_train_framework.py
@@ -10,7 +10,7 @@ from pathlib import Path
from typing import Any
import pytest
-from test_fakes import InMemoryAGFS, fake_request_context
+from test_fakes import fake_request_context
from openviking.message import Message, TextPart
from openviking.session.memory.dataclass import StoredLink
@@ -34,15 +34,6 @@ from openviking.session.train import (
Trajectory,
)
from openviking.session.train.components.reporter import ConsolePipelineReporter
-from openviking.storage.transaction import init_lock_manager, reset_lock_manager
-
-
[email protected](autouse=True)
-def _train_lock_manager():
- reset_lock_manager()
- init_lock_manager(InMemoryAGFS(), redo_recovery_enabled=False)
- yield
- reset_lock_manager()
def _case() -> Case:
@@ -463,7 +454,9 @@ async def test_training_updates_execution_metadata_epoch_each_epoch():
policy_optimizer=DummyOptimizer(),
policy_updater=DummyUpdater(),
)
- context = PipelineContext(max_epochs=2, execution_metadata={"rollout_stage": "eval_train_rollout"})
+ context = PipelineContext(
+ max_epochs=2, execution_metadata={"rollout_stage": "eval_train_rollout"}
+ )
result = await pipeline.train(
case_loader=ListCaseLoader([_case()]),
@@ -499,9 +492,10 @@ async def test_train_runs_test_eval_after_each_epoch_when_configured():
assert [item.epoch for item in result.evaluation_passes] == [0, 1]
assert result.metadata["evaluation_pass_count"] == 2
- assert [
- item.metadata.get("rollout_stage") for item in result.evaluation_passes
- ] == ["test_rollout", "test_rollout"]
+ assert [item.metadata.get("rollout_stage") for item in result.evaluation_passes] == [
+ "test_rollout",
+ "test_rollout",
+ ]
assert [item.metadata.get("eval_split") for item in result.evaluation_passes] == [
"test",
"test",
@@ -552,6 +546,7 @@ async def test_offline_policy_optimization_pipeline_epoch_hook_can_stop_training
policy_optimizer=DummyOptimizer(),
policy_updater=DummyUpdater(),
)
+
class StopTrainingHook(NoopPipelineLifecycleHook):
def __init__(self):
self.epochs: list[int] = []
@@ -871,12 +866,8 @@ async def test_streaming_policy_trainer_scopes_concurrent_submit_results_by_sour
assert {item.target_name for item in first.batch_result.plan.items} == {"case_a", "case_b"}
assert [item.target_name for item in first.plan.items] == ["case_a"]
assert [item.target_name for item in second.plan.items] == ["case_b"]
- assert first.apply_result.written_uris == [
- "viking://user/u/memories/experiences/case_a.md"
- ]
- assert second.apply_result.written_uris == [
- "viking://user/u/memories/experiences/case_b.md"
- ]
+ assert first.apply_result.written_uris == ["viking://user/u/memories/experiences/case_a.md"]
+ assert second.apply_result.written_uris == ["viking://user/u/memories/experiences/case_b.md"]
assert await trainer.close() is None
@@ -1121,6 +1112,7 @@ async def test_get_streaming_policy_trainer_returns_process_global_instance():
assert second is first
assert first.config.max_gradients_per_update == 3
+
class FakeSessionCommitClient:
def __init__(self):
self.created_sessions = []
@@ -1579,12 +1571,7 @@ def test_rollout_artifact_event_recorder_enriches_commit_result(tmp_path):
/ "trial_0"
)
commit_dir = (
- tmp_path
- / "rollouts"
- / "airline_train_task_7_task-7"
- / "epoch_0"
- / "2.train"
- / "trial_0"
+ tmp_path / "rollouts" / "airline_train_task_7_task-7" / "epoch_0" / "2.train" / "trial_0"
)
assert not (rollout_dir / "commit_result.json").exists()
commit_result = json.loads((commit_dir / "commit_result.json").read_text())
@@ -1608,22 +1595,22 @@ async def test_rollout_artifact_recorder_writes_epoch_commit_artifacts_under_com
class CommitArtifactClient:
async def read(self, uri):
assert uri == "viking://archive/memory_diff.json"
- return json.dumps({
- "operations": {
- "adds": [
- {"uri": "viking://memory/new.md", "after": "# New\nbody"}
- ],
- "updates": [
- {
- "uri": "viking://memory/old.md",
- "before": "# Old\nbody",
- "after": "# Old\nnew body",
- }
- ],
- "deletes": [],
- },
- "summary": {"total_adds": 1, "total_updates": 1, "total_deletes": 0},
- })
+ return json.dumps(
+ {
+ "operations": {
+ "adds": [{"uri": "viking://memory/new.md", "after": "# New\nbody"}],
+ "updates": [
+ {
+ "uri": "viking://memory/old.md",
+ "before": "# Old\nbody",
+ "after": "# Old\nnew body",
+ }
+ ],
+ "deletes": [],
+ },
+ "summary": {"total_adds": 1, "total_updates": 1, "total_deletes": 0},
+ }
+ )
recorder = RolloutArtifactRecorder(run_dir=tmp_path, client=CommitArtifactClient())
case = Case(
@@ -1671,12 +1658,7 @@ async def test_rollout_artifact_recorder_writes_epoch_commit_artifacts_under_com
/ "trial_0"
)
commit_dir = (
- tmp_path
- / "rollouts"
- / "airline_train_task_7_task-7"
- / "epoch_0"
- / "2.train"
- / "trial_0"
+ tmp_path / "rollouts" / "airline_train_task_7_task-7" / "epoch_0" / "2.train" / "trial_0"
)
assert (train_dir / "status.json").exists()
assert not (train_dir / "commit_result.json").exists()
diff --git a/tests/storage/test_ingest_ls_node_limit.py b/tests/storage/test_ingest_ls_node_limit.py
index bfbf6c714..08cbb637f 100644
--- a/tests/storage/test_ingest_ls_node_limit.py
+++ b/tests/storage/test_ingest_ls_node_limit.py
@@ -18,7 +18,6 @@ from __future__ import annotations
import pytest
from openviking.storage.queuefs.semantic_processor import SemanticProcessor
-from openviking.storage.transaction import NO_LOCK
class _TruncatingVikingFS:
@@ -43,16 +42,16 @@ class _TruncatingVikingFS:
entries = self._children if uri == self.TEMP else []
return entries[:node_limit] # the real ls truncates here
- async def mv(self, src, dst, ctx=None, lock_handle=None):
+ async def mv(self, src, dst, ctx=None, lease_ref=None):
self.moved.append((src, dst))
- async def rm(self, uri, recursive=False, ctx=None, lock_handle=None):
+ async def rm(self, uri, recursive=False, ctx=None, lease_ref=None):
pass
- async def mkdir(self, uri, exist_ok=False, ctx=None):
+ async def mkdir(self, uri, exist_ok=False, ctx=None, lease_ref=None):
pass
- async def delete_temp(self, uri, ctx=None):
+ async def delete_temp(self, uri, ctx=None, lease_ref=None):
pass
@@ -68,7 +67,7 @@ async def test_sync_materializes_all_children_above_default_node_limit(monkeypat
diff = await SemanticProcessor()._sync_topdown_recursive(
_TruncatingVikingFS.TEMP,
_TruncatingVikingFS.TARGET,
- lock=NO_LOCK,
+ lock=None,
)
assert len(fake.moved) == n_children, (
diff --git a/tests/storage/test_lock_observer.py b/tests/storage/test_lock_observer.py
deleted file mode 100644
index 84580886d..000000000
--- a/tests/storage/test_lock_observer.py
+++ /dev/null
@@ -1,51 +0,0 @@
-# Copyright (c) 2026 Beijing Volcano Engine Technology Co., Ltd.
-# SPDX-License-Identifier: AGPL-3.0
-"""Tests for lock observer activity tracking."""
-
-from unittest.mock import MagicMock
-
-from openviking.storage.observers.lock_observer import LockObserver
-from openviking.storage.transaction.lock_handle import LockHandle
-
-
-def _make_handle(handle_id: str, created_at: float, last_active_at: float) -> LockHandle:
- handle = LockHandle(id=handle_id)
- handle.created_at = created_at
- handle.last_active_at = last_active_at
- handle.add_lock(f"/local/{handle_id}/.path.ovlock")
- return handle
-
-
-def test_get_hanging_locks_uses_idle_time(monkeypatch):
- active_handle = _make_handle("active", created_at=0.0, last_active_at=900.0)
- stale_handle = _make_handle("stale", created_at=0.0, last_active_at=100.0)
-
- manager = MagicMock()
- manager.get_active_handles.return_value = {
- active_handle.id: active_handle,
- stale_handle.id: stale_handle,
- }
-
- monkeypatch.setattr("openviking.storage.observers.lock_observer.time.time", lambda: 1000.0)
-
- observer = LockObserver(manager)
- active_locks = observer.get_active_locks()
- active_info = next(lock for lock in active_locks if lock["id"] == active_handle.id)
-
- assert active_info["duration_seconds"] == 1000.0
- assert active_info["idle_seconds"] == 100.0
- assert [lock["id"] for lock in observer.get_hanging_locks(600)] == [stale_handle.id]
-
-
-def test_health_checks_ignore_long_running_but_active_lock(monkeypatch):
- active_handle = _make_handle("active", created_at=0.0, last_active_at=950.0)
-
- manager = MagicMock()
- manager.get_active_handles.return_value = {active_handle.id: active_handle}
-
- monkeypatch.setattr("openviking.storage.observers.lock_observer.time.time", lambda: 1000.0)
-
- observer = LockObserver(manager)
-
- assert observer.is_healthy() is True
- assert observer.has_errors() is False
diff --git a/tests/storage/test_memory_semantic_stall.py b/tests/storage/test_memory_semantic_stall.py
index ef6f58e92..628851c62 100644
--- a/tests/storage/test_memory_semantic_stall.py
+++ b/tests/storage/test_memory_semantic_stall.py
@@ -15,17 +15,6 @@ from openviking.storage.queuefs.semantic_msg import SemanticMsg
from openviking.storage.queuefs.semantic_processor import SemanticProcessor
-class _NoopLockContext:
- def __init__(self, *args, **kwargs):
- pass
-
- async def __aenter__(self):
- return self
-
- async def __aexit__(self, exc_type, exc, tb):
- return False
-
-
def _make_msg(uri="viking://user/memories", context_type="memory", **kwargs):
"""Build a minimal SemanticMsg for testing."""
defaults = {
@@ -241,7 +230,6 @@ async def test_memory_write_error_reports_error():
"openviking.storage.queuefs.semantic_processor.resolve_telemetry",
return_value=None,
),
- patch("openviking.storage.transaction.LockContext", _NoopLockContext),
patch.object(
processor,
"_generate_single_file_summary",
diff --git a/tests/storage/test_semantic_dag_incremental.py b/tests/storage/test_semantic_dag_incremental.py
index ab69653b8..38527ed54 100644
--- a/tests/storage/test_semantic_dag_incremental.py
+++ b/tests/storage/test_semantic_dag_incremental.py
@@ -11,22 +11,6 @@ from openviking.storage.queuefs.semantic_dag import SemanticDagExecutor
from openviking_cli.session.user_id import UserIdentifier
-def _mock_transaction_layer(monkeypatch):
- mock_handle = MagicMock()
- monkeypatch.setattr(
- "openviking.storage.transaction.lock_context.LockContext.__aenter__",
- AsyncMock(return_value=mock_handle),
- )
- monkeypatch.setattr(
- "openviking.storage.transaction.lock_context.LockContext.__aexit__",
- AsyncMock(return_value=False),
- )
- monkeypatch.setattr(
- "openviking.storage.transaction.get_lock_manager",
- lambda: MagicMock(),
- )
-
-
class _FakeVikingFS:
def __init__(self, tree, file_contents):
self._tree = {self._norm(k): v for k, v in tree.items()}
@@ -110,7 +94,6 @@ class _FakeProcessor:
@pytest.mark.asyncio
async def test_direct_incremental_update_uses_changes_without_temp_sync(monkeypatch):
- _mock_transaction_layer(monkeypatch)
root_uri = "viking://resources/root"
tree = {
diff --git a/tests/storage/test_semantic_dag_skip_files.py b/tests/storage/test_semantic_dag_skip_files.py
index 69448e97d..a195a4210 100644
--- a/tests/storage/test_semantic_dag_skip_files.py
+++ b/tests/storage/test_semantic_dag_skip_files.py
@@ -1,8 +1,6 @@
# Copyright (c) 2026 Beijing Volcano Engine Technology Co., Ltd.
# SPDX-License-Identifier: AGPL-3.0
-from unittest.mock import AsyncMock, MagicMock
-
import pytest
from openviking.server.identity import RequestContext, Role
@@ -10,23 +8,6 @@ from openviking.storage.queuefs.semantic_dag import SemanticDagExecutor
from openviking_cli.session.user_id import UserIdentifier
-def _mock_transaction_layer(monkeypatch):
- """Patch lock layer to no-op for DAG tests."""
- mock_handle = MagicMock()
- monkeypatch.setattr(
- "openviking.storage.transaction.lock_context.LockContext.__aenter__",
- AsyncMock(return_value=mock_handle),
- )
- monkeypatch.setattr(
- "openviking.storage.transaction.lock_context.LockContext.__aexit__",
- AsyncMock(return_value=False),
- )
- monkeypatch.setattr(
- "openviking.storage.transaction.get_lock_manager",
- lambda: MagicMock(),
- )
-
-
class _FakeVikingFS:
def __init__(self, tree):
self._tree = tree
@@ -93,7 +74,6 @@ class _DummyTracker:
)
async def test_messages_jsonl_excluded_from_summary(monkeypatch, root_uri):
"""messages.jsonl should be skipped by _list_dir and never summarized."""
- _mock_transaction_layer(monkeypatch)
tree = {
root_uri: [
{"name": "messages.jsonl", "isDir": False},
@@ -134,7 +114,6 @@ async def test_messages_jsonl_excluded_from_summary(monkeypatch, root_uri):
)
async def test_messages_jsonl_excluded_in_subdirectory(monkeypatch, root_uri):
"""messages.jsonl in a subdirectory should also be skipped."""
- _mock_transaction_layer(monkeypatch)
tree = {
root_uri: [
{"name": "subdir", "isDir": True},
diff --git a/tests/storage/test_semantic_dag_stats.py b/tests/storage/test_semantic_dag_stats.py
index 31b057edf..aec37012c 100644
--- a/tests/storage/test_semantic_dag_stats.py
+++ b/tests/storage/test_semantic_dag_stats.py
@@ -2,7 +2,6 @@
# SPDX-License-Identifier: AGPL-3.0
import asyncio
-from unittest.mock import AsyncMock, MagicMock
import pytest
@@ -107,21 +106,6 @@ async def test_semantic_dag_stats_collects_nodes(monkeypatch):
lambda: _DummyTracker(),
)
- # Mock lock layer: LockContext as no-op passthrough
- mock_handle = MagicMock()
- monkeypatch.setattr(
- "openviking.storage.transaction.lock_context.LockContext.__aenter__",
- AsyncMock(return_value=mock_handle),
- )
- monkeypatch.setattr(
- "openviking.storage.transaction.lock_context.LockContext.__aexit__",
- AsyncMock(return_value=False),
- )
- monkeypatch.setattr(
- "openviking.storage.transaction.get_lock_manager",
- lambda: MagicMock(),
- )
-
processor = _FakeProcessor()
ctx = RequestContext(user=UserIdentifier("acc1", "user1"), role=Role.USER)
executor = SemanticDagExecutor(
@@ -141,7 +125,11 @@ async def test_semantic_dag_stats_collects_nodes(monkeypatch):
assert stats.in_progress_nodes == 0
assert processor.vectorized_dirs == [f"{root_uri}/child", root_uri]
assert sorted(processor.vectorized_files) == sorted(
- [f"{root_uri}/a.txt", f"{root_uri}/b.txt", f"{root_uri}/child/c.txt"]
+ [
+ f"{root_uri}/a.txt",
+ f"{root_uri}/b.txt",
+ f"{root_uri}/child/c.txt",
+ ]
)
@@ -243,20 +231,6 @@ async def test_semantic_dag_skip_vectorization_does_not_schedule_tasks(monkeypat
lambda: tracker,
)
- mock_handle = MagicMock()
- monkeypatch.setattr(
- "openviking.storage.transaction.lock_context.LockContext.__aenter__",
- AsyncMock(return_value=mock_handle),
- )
- monkeypatch.setattr(
- "openviking.storage.transaction.lock_context.LockContext.__aexit__",
- AsyncMock(return_value=False),
- )
- monkeypatch.setattr(
- "openviking.storage.transaction.get_lock_manager",
- lambda: MagicMock(),
- )
-
processor = _FakeProcessor()
ctx = RequestContext(user=UserIdentifier("acc1", "user1"), role=Role.USER)
executor = SemanticDagExecutor(
diff --git a/tests/storage/test_semantic_processor_lock_ownership.py b/tests/storage/test_semantic_processor_lock_ownership.py
index 267ec7fe2..09d3f5b3c 100644
--- a/tests/storage/test_semantic_processor_lock_ownership.py
+++ b/tests/storage/test_semantic_processor_lock_ownership.py
@@ -5,280 +5,55 @@ from __future__ import annotations
import pytest
-from openviking.storage.errors import LockAcquisitionError
-from openviking.storage.queuefs.semantic_dag import DagStats
-from openviking.storage.queuefs.semantic_lock import SemanticLockScope
from openviking.storage.queuefs.semantic_msg import SemanticMsg
from openviking.storage.queuefs.semantic_processor import SemanticProcessor
-from openviking.storage.transaction import BorrowedLockLease, LockHandoffRef
-class _FakeHandle:
- def __init__(self, handle_id: str):
- self.id = handle_id
- self.locks = ["/fake/root/.path.ovlock"]
+class _FakePathLock:
+ """Mock for _async_agfs pathlock operations."""
-
-class _FakeLockManager:
def __init__(self):
- self._handles = {"lock-1": _FakeHandle("lock-1")}
- self.release_calls = []
-
- def get_handle(self, handle_id: str):
- return self._handles.get(handle_id)
-
- async def release(self, handle):
- self.release_calls.append(handle.id)
- self._handles.pop(handle.id, None)
-
- def create_handle(self):
- handle = _FakeHandle("new-lock")
- self._handles[handle.id] = handle
- return handle
-
- async def acquire_tree(self, handle, lock_path):
- del handle, lock_path
- return True
-
-
-class _RecoveringLockManager:
- def __init__(self):
- self._handles = {}
- self.acquire_tree_calls = []
- self.release_calls = []
-
- async def get_handle_async(self, handle_id):
- return self._handles.get(handle_id)
-
- async def adopt_handle_async(self, handle_id, lock_paths):
- del handle_id, lock_paths
- return None
-
- def get_handle(self, handle_id):
- return self._handles.get(handle_id)
+ self.release_calls: list[str] = []
- def create_handle(self):
- handle = _FakeHandle("new-lock")
- handle.locks = []
- self._handles[handle.id] = handle
- return handle
-
- async def acquire_tree(self, handle, lock_path):
- self.acquire_tree_calls.append(lock_path)
- handle.locks.append(f"{lock_path}/.path.ovlock")
- return True
-
- async def release(self, handle):
- self.release_calls.append(handle.id)
- self._handles.pop(handle.id, None)
+ async def pathlock_release(self, lease):
+ self.release_calls.append(lease["id"])
class _FakeVikingFS:
+ def __init__(self, pathlock=None):
+ self._async_agfs = pathlock or _FakePathLock()
+
async def exists(self, uri, ctx=None):
del uri, ctx
return False
+ async def ls(self, uri, node_limit=None, ctx=None):
+ del uri, node_limit, ctx
+ return []
+
def _uri_to_path(self, uri, ctx=None):
del ctx
return f"/fake/{uri.replace('://', '/').strip('/')}"
@pytest.mark.asyncio
-async def test_semantic_processor_borrows_caller_owned_lock(monkeypatch):
+async def test_memory_semantic_directory_does_not_release_borrowed_lock(monkeypatch):
processor = SemanticProcessor()
- lock_manager = _FakeLockManager()
-
- class _FakeDagExecutor:
- def __init__(self, **kwargs):
- self.lock = kwargs["lock"]
- self.stale = False
-
- async def run(self, root_uri):
- assert root_uri == "viking://resources/demo"
- assert self.lock.handle_id == "lock-1"
-
- def get_stats(self):
- return DagStats()
+ pathlock = _FakePathLock()
+ borrowed_lease = {"id": "borrowed-lock", "owned": False}
monkeypatch.setattr(
"openviking.storage.queuefs.semantic_processor.get_viking_fs",
- lambda: _FakeVikingFS(),
- )
- monkeypatch.setattr(
- "openviking.storage.queuefs.semantic_processor.SemanticDagExecutor",
- lambda **kwargs: _FakeDagExecutor(**kwargs),
- )
- monkeypatch.setattr(
- "openviking.storage.transaction.get_lock_manager",
- lambda: lock_manager,
+ lambda: _FakeVikingFS(pathlock),
)
- await processor.on_dequeue(
+ await processor._process_memory_directory(
SemanticMsg(
- uri="viking://resources/demo",
- context_type="resource",
+ uri="viking://memory/demo",
+ context_type="memory",
recursive=False,
- ).to_dict(),
- lock=BorrowedLockLease.from_handle(lock_manager, lock_manager.get_handle("lock-1")),
- )
-
- assert lock_manager.release_calls == []
-
-
-async def test_semantic_processor_recovers_stale_non_tree_handoff(monkeypatch):
- processor = SemanticProcessor()
- lock_manager = _RecoveringLockManager()
-
- class _FakeDagExecutor:
- def __init__(self, **kwargs):
- self.lock = kwargs["lock"]
- self.stale = False
-
- async def run(self, root_uri):
- assert root_uri == "viking://resources/demo"
- assert self.lock.handle_id == "new-lock"
- await self.lock.close()
-
- def get_stats(self):
- return DagStats()
-
- monkeypatch.setattr(
- "openviking.storage.queuefs.semantic_processor.get_viking_fs",
- lambda: _FakeVikingFS(),
- )
- monkeypatch.setattr(
- "openviking.storage.queuefs.semantic_processor.SemanticDagExecutor",
- lambda **kwargs: _FakeDagExecutor(**kwargs),
- )
- monkeypatch.setattr(
- "openviking.storage.queuefs.semantic_lock.get_lock_manager",
- lambda: lock_manager,
- )
-
- await processor.on_dequeue(
- SemanticMsg(
- uri="viking://resources/demo",
- context_type="resource",
- recursive=False,
- lock_handoff=LockHandoffRef(
- handle_id="stale-lock",
- lock_paths=("/fake/viking/resources/.mw_exact_demo.deadbeef",),
- ),
- ).to_dict()
- )
-
- assert lock_manager.acquire_tree_calls == ["/fake/viking/resources/demo"]
- assert lock_manager.release_calls == ["new-lock"]
-
-
-async def test_semantic_lock_scope_reacquires_tree_lock_when_handoff_handle_is_stale(
- monkeypatch,
-):
- lock_manager = _RecoveringLockManager()
- monkeypatch.setattr(
- "openviking.storage.queuefs.semantic_lock.get_lock_manager",
- lambda: lock_manager,
- )
-
- scope = await SemanticLockScope.resolve(
- LockHandoffRef(
- handle_id="stale-lock",
- lock_paths=("/local/default/resources/CONTRIBUTING_CN_3/.path.ovlock",),
- ),
- fallback_path_factory=lambda: (_ for _ in ()).throw(
- AssertionError("tree handoffs must not evaluate the fallback path")
- ),
- )
-
- try:
- assert scope.lock.handle_id == "new-lock"
- assert lock_manager.acquire_tree_calls == ["/local/default/resources/CONTRIBUTING_CN_3"]
- finally:
- await scope.close()
-
- assert lock_manager.release_calls == ["new-lock"]
-
-
-async def test_semantic_lock_scope_reacquires_fallback_path_for_stale_non_tree_handoff(
- monkeypatch,
-):
- lock_manager = _RecoveringLockManager()
- monkeypatch.setattr(
- "openviking.storage.queuefs.semantic_lock.get_lock_manager",
- lambda: lock_manager,
- )
-
- scope = await SemanticLockScope.resolve(
- LockHandoffRef(
- handle_id="stale-lock",
- lock_paths=("/local/default/resources/.mw_exact_demo.deadbeef",),
),
- fallback_path_factory=lambda: "/local/default/resources/demo",
+ lock=borrowed_lease,
)
- try:
- assert scope.lock.handle_id == "new-lock"
- assert lock_manager.acquire_tree_calls == ["/local/default/resources/demo"]
- finally:
- await scope.close()
-
- assert lock_manager.release_calls == ["new-lock"]
-
-
-async def test_semantic_processor_lock_error_requeues_without_circuit_breaker(monkeypatch):
- processor = SemanticProcessor()
- reenqueue_calls = []
- success_called = False
- requeue_called = False
- error_called = False
-
- async def _reenqueue(msg):
- reenqueue_calls.append(msg.uri)
-
- def on_success():
- nonlocal success_called
- success_called = True
-
- def on_requeue():
- nonlocal requeue_called
- requeue_called = True
-
- def on_error(error_msg, error_data=None):
- del error_msg, error_data
- nonlocal error_called
- error_called = True
-
- def _record_failure(error):
- raise AssertionError(f"lock errors must not trip circuit breaker: {error}")
-
- processor.set_callbacks(on_success, on_requeue, on_error)
- processor._circuit_breaker.record_failure = _record_failure
-
- monkeypatch.setattr(processor, "_reenqueue_semantic_msg", _reenqueue)
- monkeypatch.setattr(
- "openviking.storage.queuefs.semantic_processor.SemanticLockScope.resolve",
- lambda *args, **kwargs: (_ for _ in ()).throw(
- LockAcquisitionError("lock handle is no longer active")
- ),
- )
-
- msg = SemanticMsg(
- uri="viking://resources/CONTRIBUTING_CN_3",
- context_type="resource",
- recursive=True,
- lock_handoff=LockHandoffRef(
- handle_id="stale-lock",
- lock_paths=("/local/default/resources/CONTRIBUTING_CN_3/.path.ovlock",),
- ),
- )
-
- await processor.on_dequeue(msg.to_dict())
-
- assert reenqueue_calls == ["viking://resources/CONTRIBUTING_CN_3"]
- assert requeue_called is True
- assert success_called is True
- assert error_called is False
+ assert pathlock.release_calls == []
diff --git a/tests/storage/test_semantic_processor_mv_vector_store.py b/tests/storage/test_semantic_processor_mv_vector_store.py
index 015861819..ea0011c87 100644
--- a/tests/storage/test_semantic_processor_mv_vector_store.py
+++ b/tests/storage/test_semantic_processor_mv_vector_store.py
@@ -1,4 +1,3 @@
-from contextlib import asynccontextmanager
from unittest.mock import AsyncMock
import pytest
@@ -18,13 +17,6 @@ async def test_mv_canonicalizes_user_shorthand_before_vector_update(monkeypatch)
fs._copy_for_mv = AsyncMock()
fs._update_vector_store_uris = AsyncMock()
- @asynccontextmanager
- async def unlocked(*_args, **_kwargs):
- yield None
-
- monkeypatch.setattr("openviking.storage.transaction.get_lock_manager", lambda: None)
- monkeypatch.setattr("openviking.storage.transaction.LockContext", unlocked)
-
await fs.mv(
"viking://user/peers/vaka/memories/profile.md",
"viking://user/memories/profile.md",
diff --git a/tests/storage/test_semantic_processor_target_preexisting.py b/tests/storage/test_semantic_processor_target_preexisting.py
index 109d33a55..f0b70bed4 100644
--- a/tests/storage/test_semantic_processor_target_preexisting.py
+++ b/tests/storage/test_semantic_processor_target_preexisting.py
@@ -5,7 +5,6 @@ import pytest
from openviking.storage.queuefs.semantic_msg import SemanticMsg
from openviking.storage.queuefs.semantic_processor import DiffResult, SemanticProcessor
-from openviking.storage.transaction import NO_LOCK
class _FakeVikingFS:
@@ -36,6 +35,7 @@ class _SyncVikingFS:
],
}
self.deleted_temp = []
+ self.mutation_leases = []
async def exists(self, uri, ctx=None):
return uri in self.entries
@@ -49,16 +49,20 @@ class _SyncVikingFS:
async def read_file(self, uri, ctx=None):
return self.contents.get(uri, "")
- async def rm(self, uri, recursive=False, ctx=None, lock_handle=None):
+ async def rm(self, uri, recursive=False, ctx=None, lease_ref=None):
+ self.mutation_leases.append(("rm", uri, lease_ref))
self.contents.pop(uri, None)
- async def mv(self, src, dst, ctx=None, lock_handle=None):
+ async def mv(self, src, dst, ctx=None, lease_ref=None):
+ self.mutation_leases.append(("mv", dst, lease_ref))
self.contents[dst] = self.contents.pop(src)
- async def mkdir(self, uri, exist_ok=False, ctx=None):
+ async def mkdir(self, uri, exist_ok=False, ctx=None, lease_ref=None):
+ self.mutation_leases.append(("mkdir", uri, lease_ref))
self.entries.setdefault(uri, [])
- async def delete_temp(self, uri, ctx=None):
+ async def delete_temp(self, uri, ctx=None, lease_ref=None):
+ self.mutation_leases.append(("delete_temp", uri, lease_ref))
self.deleted_temp.append(uri)
@@ -93,7 +97,7 @@ async def test_target_source_syncs_before_semantic_dag(monkeypatch):
)
monkeypatch.setattr(
"openviking.storage.queuefs.semantic_processor.SemanticLockScope.resolve",
- AsyncMock(return_value=SimpleNamespace(lock=NO_LOCK, close=AsyncMock())),
+ AsyncMock(return_value=SimpleNamespace(lock=None, close=AsyncMock())),
)
_FakeDagExecutor.calls = []
@@ -127,6 +131,11 @@ async def test_target_source_syncs_before_semantic_dag(monkeypatch):
@pytest.mark.asyncio
async def test_sync_diff_reports_target_uris_and_preserves_sidecars(monkeypatch):
fake_fs = _SyncVikingFS()
+ lease = {
+ "lease_ref": "outer-tree-ref",
+ "owner_id": "outer-tree-owner",
+ "owned": False,
+ }
monkeypatch.setattr(
"openviking.storage.queuefs.semantic_processor.get_viking_fs",
lambda: fake_fs,
@@ -135,7 +144,7 @@ async def test_sync_diff_reports_target_uris_and_preserves_sidecars(monkeypatch)
diff = await SemanticProcessor()._sync_topdown_recursive(
"viking://temp/import",
"viking://resources/root",
- lock=NO_LOCK,
+ lock=lease,
)
assert diff.to_changes() == {
@@ -149,6 +158,13 @@ async def test_sync_diff_reports_target_uris_and_preserves_sidecars(monkeypatch)
)
assert fake_fs.contents["viking://resources/root/.abstract.md"] == "old abstract"
assert fake_fs.deleted_temp == ["viking://temp/import"]
+ assert fake_fs.mutation_leases
+ assert all(
+ mutation_lease is lease
+ for operation, _, mutation_lease in fake_fs.mutation_leases
+ if operation != "delete_temp"
+ )
+ assert fake_fs.mutation_leases[-1] == ("delete_temp", "viking://temp/import", None)
@pytest.mark.asyncio
@@ -164,7 +180,7 @@ async def test_sync_missing_source_never_touches_target(monkeypatch):
await SemanticProcessor()._sync_topdown_recursive(
"viking://temp/missing",
"viking://resources/root",
- lock=NO_LOCK,
+ lock=None,
)
fake_fs.ls.assert_not_awaited()
diff --git a/tests/storage/test_semantic_queue_memory_dedupe.py b/tests/storage/test_semantic_queue_memory_dedupe.py
index d8a810cda..c69c4320b 100644
--- a/tests/storage/test_semantic_queue_memory_dedupe.py
+++ b/tests/storage/test_semantic_queue_memory_dedupe.py
@@ -101,38 +101,24 @@ async def test_coalesced_semantic_messages_mark_old_version_stale():
assert not is_semantic_msg_stale(second)
-class _FakeHandle:
- def __init__(self):
- self.id = "lock-1"
- self.locks = []
-
+class _FakePathLock:
+ """Mock for _async_agfs pathlock operations."""
-class _FakeLockManager:
def __init__(self):
self.acquired_batches = []
self.release_calls = []
- def create_handle(self):
- return _FakeHandle()
-
- def get_handle(self, handle_id):
- del handle_id
- return None
-
- async def acquire_exact_path_batch(self, handle, paths):
+ async def pathlock_acquire_exact_batch(self, paths):
self.acquired_batches.append(paths)
- handle.locks.extend(paths)
- return True
-
- async def release(self, handle):
- self.release_calls.append(handle.id)
+ return {"id": "lock-1"}
- async def release_selected(self, handle, lock_paths):
- del handle, lock_paths
+ async def pathlock_release(self, lease):
+ self.release_calls.append(lease["id"])
class _FakeVikingFS:
- def __init__(self):
+ def __init__(self, pathlock=None):
+ self._async_agfs = pathlock or _FakePathLock()
self.writes = []
def _uri_to_path(self, uri, ctx=None):
@@ -155,8 +141,8 @@ class _FakeMemoryDirFS:
@pytest.mark.asyncio
async def test_stale_memory_semantic_write_is_skipped(monkeypatch):
- lock_manager = _FakeLockManager()
- viking_fs = _FakeVikingFS()
+ pathlock = _FakePathLock()
+ viking_fs = _FakeVikingFS(pathlock)
processor = SemanticProcessor()
coalesce_key = f"memory|acc|u|p|viking://user/default/memories/preferences/{uuid4().hex}"
@@ -175,8 +161,6 @@ async def test_stale_memory_semantic_write_is_skipped(monkeypatch):
await q.enqueue(first)
await q.enqueue(latest)
- monkeypatch.setattr("openviking.storage.transaction.get_lock_manager", lambda: lock_manager)
-
wrote_first = await processor._write_memory_directory_semantics(
msg=first,
viking_fs=viking_fs,
@@ -196,7 +180,7 @@ async def test_stale_memory_semantic_write_is_skipped(monkeypatch):
assert not wrote_first
assert wrote_latest
- assert lock_manager.acquired_batches == [
+ assert pathlock.acquired_batches == [
[
"/fake/viking/user/default/memories/preferences/.overview.md",
"/fake/viking/user/default/memories/preferences/.abstract.md",
diff --git a/tests/storage/test_viking_fs_async_stat.py b/tests/storage/test_viking_fs_async_stat.py
deleted file mode 100644
index 920e53f07..000000000
--- a/tests/storage/test_viking_fs_async_stat.py
+++ /dev/null
@@ -1,36 +0,0 @@
-# Copyright (c) 2026 Beijing Volcano Engine Technology Co., Ltd.
-# SPDX-License-Identifier: AGPL-3.0
-
-import pytest
-
-import openviking.storage.transaction as transaction_module
-from openviking.storage.viking_fs import VikingFS
-
-
-class _StatAGFS:
- def stat(self, path):
- return {"name": path.rsplit("/", 1)[-1], "isDir": False}
-
-
-class _AsyncOnlyLockManager:
- def __init__(self):
- self.paths = []
-
- async def is_path_locked_async(self, path, ignore_stale=True):
- self.paths.append((path, ignore_stale))
- return True
-
- def is_path_locked(self, path, ignore_stale=True):
- raise AssertionError("stat() should use the async lock lookup")
-
-
-async def test_stat_uses_async_lock_lookup(monkeypatch):
- lock_manager = _AsyncOnlyLockManager()
- monkeypatch.setattr(transaction_module, "get_lock_manager", lambda: lock_manager)
-
- fs = VikingFS(agfs=_StatAGFS())
- result = await fs.stat("viking://resources/file.txt")
-
- assert result["isLocked"] is True
- assert lock_manager.paths == [("/local/default/resources/file.txt", True)]
diff --git a/tests/storage/test_viking_fs_tree.py b/tests/storage/test_viking_fs_tree.py
index 4b00e7407..9033f3074 100644
--- a/tests/storage/test_viking_fs_tree.py
+++ b/tests/storage/test_viking_fs_tree.py
@@ -12,7 +12,9 @@ from openviking_cli.session.user_id import UserIdentifier
class _DummyAgfs:
- pass
+ def stat(self, _path, ctx=None):
+ """Return a minimal stat payload for paths assumed to exist in tree tests."""
+ return {}
class _FixedDatetime(datetime):
@@ -136,7 +138,7 @@ async def default_batch_fetch(entries, abs_limit, **_kwargs):
[
("resources", "/local/test_account", True),
("user", "/local/test_account", True),
- ("agent", "/local/test_account", False),
+ ("agent", "/local/test_account", True),
("session", "/local/test_account", False),
("tasks", "/local/test_account", False),
("_system", "/local/test_account", False),
diff --git a/tests/storage/test_viking_fs_write_locking.py b/tests/storage/test_viking_fs_write_locking.py
index 6765cb9ed..6e1d22986 100644
--- a/tests/storage/test_viking_fs_write_locking.py
+++ b/tests/storage/test_viking_fs_write_locking.py
@@ -1,6 +1,10 @@
+from unittest.mock import AsyncMock
+
import pytest
+from openviking.server.identity import RequestContext, Role
from openviking.storage.viking_fs import VikingFS
+from openviking_cli.session.user_id import UserIdentifier
class _FakeAGFS:
@@ -25,63 +29,93 @@ class _FakeAGFS:
return self.storage[path]
-class _RecordingLockContext:
- """Record LockContext arguments so tests can assert dual-path locking."""
+class _AsyncAppendAGFS:
+ """Async AGFS stub that records append lock ordering."""
- calls = []
+ def __init__(self):
+ self.events = []
- def __init__(self, lock_manager, paths, lock_mode="exact", **kwargs):
- """Store lock paths and mode while ignoring unrelated details."""
- self.lock_manager = lock_manager
- self.paths = list(paths)
- self.lock_mode = lock_mode
- self.kwargs = kwargs
+ async def pathlock_acquire_exact(self, path):
+ """Record exact acquisition and return an opaque lease ref."""
+ lease = {"lease_ref": "lease-1"}
+ self.events.append(("acquire", path, lease))
+ return lease
- async def __aenter__(self):
- """Record the call on context entry."""
- type(self).calls.append((self.paths, self.lock_mode, self.kwargs))
- return self
+ async def pathlock_release(self, lease):
+ """Record lease release."""
+ self.events.append(("release", lease))
- async def __aexit__(self, exc_type, exc, tb):
- """Do not swallow exceptions on exit."""
- return False
+ async def read(self, path, fs_ctx=None):
+ """Record reads with propagated fs_ctx and return existing content."""
+ self.events.append(("read", path, fs_ctx))
+ return b"old"
+ async def write(self, path, data, fs_ctx=None):
+ """Record writes with propagated fs_ctx."""
+ self.events.append(("write", path, data, fs_ctx))
+ return len(data)
- ("method_name", "args", "expected_bytes"),
- [
- ("write_file", ("hello",), b"hello"),
- ("append_file", (" world",), b"hello world"),
- ],
-)
-async def test_encrypted_writes_lock_final_and_temp_paths(
- monkeypatch, method_name, args, expected_bytes
-):
- """Encrypted writes must lock both the final file path and the hidden temp path."""
- import openviking.storage.transaction as transaction_module
- _RecordingLockContext.calls.clear()
- monkeypatch.setattr(transaction_module, "LockContext", _RecordingLockContext)
- monkeypatch.setattr(transaction_module, "get_lock_manager", lambda: object())
+class _AsyncMoveAGFS:
+ """Async AGFS stub that records move lock ownership and release."""
- agfs = _FakeAGFS()
- agfs.storage["/local/default/resources/note.md"] = b"hello"
- fs = VikingFS(agfs=agfs, encryptor=object())
+ def __init__(self, source_is_dir=False):
+ self.acquire_calls = []
+ self.tree_calls = []
+ self.release_calls = []
+ self.rm_calls = []
+ self.source_is_dir = source_is_dir
- await getattr(fs, method_name)("viking://resources/note.md", *args)
+ async def stat(self, path):
+ """Return the configured source kind and a missing destination."""
+ if path.endswith("/source.md") or path.endswith("/source"):
+ return {"isDir": self.source_is_dir}
+ raise FileNotFoundError(path)
+
+ async def pathlock_acquire_batch(
+ self,
+ requests,
+ timeout_secs=0.0,
+ owner_lease_ref=None,
+ ):
+ """Record the operation lease request."""
+ self.acquire_calls.append((requests, owner_lease_ref))
+ return {
+ "lease_ref": "operation-ref",
+ "owner_id": (owner_lease_ref["owner_id"] if owner_lease_ref else "operation-owner"),
+ "ownership_ref": "operation-ownership",
+ "owned": True,
+ }
+
+ async def pathlock_acquire_tree(
+ self,
+ path,
+ timeout_secs=0.0,
+ owner_lease_ref=None,
+ ):
+ """Record a temporary Tree extension used only for cleanup."""
+ del timeout_secs
+ self.tree_calls.append((path, owner_lease_ref))
+ return {
+ "lease_ref": "cleanup-ref",
+ "owner_id": owner_lease_ref["owner_id"],
+ "ownership_ref": "cleanup-ownership",
+ "owned": True,
+ }
+
+ async def pathlock_release(self, lease):
+ """Record operation lease release."""
+ self.release_calls.append(lease)
+
+ async def rm(self, path, recursive=False, fs_ctx=None):
+ """Accept source removal under the operation lease."""
+ self.rm_calls.append((path, recursive, fs_ctx))
+ return {"path": path, "recursive": recursive, "fs_ctx": fs_ctx}
- assert _RecordingLockContext.calls == [
- (
- [
- "/local/default/resources/note.md",
- "/local/default/temp/.encrypt_stage/571a25aab6e6bca05a60a6e4aec646389a9ac38237daf55ceda4f72f3d1b4afe.encrypt",
- ],
- "exact",
- {"timeout": 1.0, "handle": None},
- )
- ]
- assert agfs.storage["/local/default/resources/note.md"] == expected_bytes
+
+def _default_ctx() -> RequestContext:
+ """Return a stable root request context for pathlock fs_ctx tests."""
+ return RequestContext(user=UserIdentifier.the_default_user(), role=Role(Role.ROOT))
@pytest.mark.parametrize(
@@ -113,3 +147,190 @@ def test_encrypted_temp_path_mapping_matches_rust(final_path, temp_path):
"""Keep Python temp-path mapping aligned with the Rust encryption wrapper."""
fs = VikingFS(agfs=_FakeAGFS(), encryptor=object())
assert fs._encrypted_temp_path(final_path) == temp_path
+
+
+def test_pathlock_fs_ctx_rejects_malformed_explicit_lease():
+ """An explicit malformed lease must fail instead of enabling a new auto-lock."""
+ fs = VikingFS(agfs=_FakeAGFS())
+
+ with pytest.raises(ValueError, match="lease_ref"):
+ fs._pathlock_fs_ctx(_default_ctx(), {})
+
+
+async def test_append_file_holds_exact_lease_across_read_and_write(monkeypatch):
+ """append_file should keep read and rewrite inside one exact pathlock lease."""
+ fake = _AsyncAppendAGFS()
+ fs = VikingFS(agfs=_FakeAGFS())
+ fs._async_agfs = fake # type: ignore[assignment]
+
+ async def ensure_parent_dirs(path, ctx=None, lease_ref=None):
+ """Record parent creation boundary without touching storage."""
+ fake.events.append(("ensure_parent", path, lease_ref))
+
+ monkeypatch.setattr(fs, "_ensure_parent_dirs", ensure_parent_dirs)
+ monkeypatch.setattr(fs, "_ensure_mutable_access", lambda _uri, _ctx=None: None)
+ monkeypatch.setattr(
+ fs,
+ "_uri_to_path",
+ lambda _uri, **_kwargs: "/local/default/resources/a.md",
+ )
+ monkeypatch.setattr(fs, "_ctx_or_default", lambda _ctx=None: _default_ctx())
+
+ await fs.append_file("viking://a.md", "+new")
+
+ assert fake.events[0] == ("ensure_parent", "/local/default/resources/a.md", None)
+ assert fake.events[1][0] == "acquire"
+ assert fake.events[2][0:2] == ("read", "/local/default/resources/a.md")
+ assert fake.events[2][2]["lease_ref"] == "lease-1"
+ assert fake.events[3][0:3] == (
+ "write",
+ "/local/default/resources/a.md",
+ b"old+new",
+ )
+ assert fake.events[3][3]["lease_ref"] == "lease-1"
+ assert fake.events[4] == ("release", {"lease_ref": "lease-1"})
+
+
+async def test_mv_extends_outer_lease_with_owned_capability(monkeypatch):
+ """Move must acquire uncovered source locks with the outer owned capability."""
+ fake = _AsyncMoveAGFS()
+ fs = VikingFS(agfs=_FakeAGFS())
+ fs._async_agfs = fake # type: ignore[assignment]
+ outer = {
+ "lease_ref": "outer-ref",
+ "owner_id": "outer-owner",
+ "ownership_ref": "outer-ownership",
+ "owned": True,
+ }
+ copied_with = []
+
+ monkeypatch.setattr(fs, "_ensure_mutable_access", lambda *_args, **_kwargs: None)
+ monkeypatch.setattr(fs, "_ensure_delete_access", lambda *_args, **_kwargs: None)
+ monkeypatch.setattr(
+ fs,
+ "_uri_to_path",
+ lambda uri, **_kwargs: (
+ "/local/default/temp/source.md"
+ if uri == "viking://temp/source.md"
+ else "/local/default/resources/target.md"
+ ),
+ )
+ monkeypatch.setattr(fs, "_collect_uris", AsyncMock(return_value=[]))
+ monkeypatch.setattr(fs, "_delete_from_vector_store", AsyncMock())
+ monkeypatch.setattr(fs, "_update_vector_store_uris", AsyncMock())
+
+ async def record_copy(**kwargs):
+ """Record the lease used by the copy stage."""
+ copied_with.append(kwargs["lease_ref"])
+
+ monkeypatch.setattr(fs, "_copy_for_mv", record_copy)
+
+ await fs.mv(
+ "viking://temp/source.md",
+ "viking://resources/target.md",
+ ctx=_default_ctx(),
+ lease_ref=outer,
+ )
+
+ assert fake.acquire_calls[0][1] == outer
+ assert copied_with[0]["lease_ref"] == "operation-ref"
+ assert fake.release_calls == [copied_with[0]]
+
+
+async def test_directory_mv_uses_source_tree_and_destination_exact(monkeypatch):
+ """Directory move must not hold a destination Tree lock for the whole copy."""
+ fake = _AsyncMoveAGFS(source_is_dir=True)
+ fs = VikingFS(agfs=_FakeAGFS())
+ fs._async_agfs = fake # type: ignore[assignment]
+
+ monkeypatch.setattr(fs, "_ensure_mutable_access", lambda *_args, **_kwargs: None)
+ monkeypatch.setattr(fs, "_ensure_delete_access", lambda *_args, **_kwargs: None)
+ monkeypatch.setattr(
+ fs,
+ "_uri_to_path",
+ lambda uri, **_kwargs: (
+ "/local/default/temp/source"
+ if uri == "viking://temp/source"
+ else "/local/default/resources/target"
+ ),
+ )
+ monkeypatch.setattr(fs, "_collect_uris", AsyncMock(return_value=[]))
+ monkeypatch.setattr(fs, "_delete_from_vector_store", AsyncMock())
+ monkeypatch.setattr(fs, "_update_vector_store_uris", AsyncMock())
+ monkeypatch.setattr(fs, "_copy_for_mv", AsyncMock())
+
+ await fs.mv(
+ "viking://temp/source",
+ "viking://resources/target",
+ ctx=_default_ctx(),
+ )
+
+ assert fake.acquire_calls[0][0] == [
+ {"path": "/local/default/temp/source", "kind": "tree"},
+ {"path": "/local/default/resources/target", "kind": "exact"},
+ ]
+
+
+async def test_directory_mv_uses_temporary_tree_only_for_failed_copy_cleanup(monkeypatch):
+ """Failed directory move must acquire and release a cleanup-only target Tree."""
+ fake = _AsyncMoveAGFS(source_is_dir=True)
+ fs = VikingFS(agfs=_FakeAGFS())
+ fs._async_agfs = fake # type: ignore[assignment]
+
+ monkeypatch.setattr(fs, "_ensure_mutable_access", lambda *_args, **_kwargs: None)
+ monkeypatch.setattr(fs, "_ensure_delete_access", lambda *_args, **_kwargs: None)
+ monkeypatch.setattr(
+ fs,
+ "_uri_to_path",
+ lambda uri, **_kwargs: (
+ "/local/default/temp/source"
+ if uri == "viking://temp/source"
+ else "/local/default/resources/target"
+ ),
+ )
+ monkeypatch.setattr(fs, "_collect_uris", AsyncMock(return_value=[]))
+ monkeypatch.setattr(fs, "_delete_from_vector_store", AsyncMock())
+ monkeypatch.setattr(
+ fs,
+ "_update_vector_store_uris",
+ AsyncMock(side_effect=RuntimeError("vector update failed")),
+ )
+ monkeypatch.setattr(fs, "_copy_for_mv", AsyncMock())
+
+ with pytest.raises(RuntimeError, match="vector update failed"):
+ await fs.mv(
+ "viking://temp/source",
+ "viking://resources/target",
+ ctx=_default_ctx(),
+ )
+
+ assert fake.tree_calls == [
+ (
+ "/local/default/resources/target",
+ {
+ "lease_ref": "operation-ref",
+ "owner_id": "operation-owner",
+ "ownership_ref": "operation-ownership",
+ "owned": True,
+ },
+ )
+ ]
+ assert fake.rm_calls[0][2]["lease_ref"] == "cleanup-ref"
+ assert fake.release_calls == [
+ {
+ "lease_ref": "cleanup-ref",
+ "owner_id": "operation-owner",
+ "ownership_ref": "cleanup-ownership",
+ "owned": True,
+ },
+ {
+ "lease_ref": "operation-ref",
+ "owner_id": "operation-owner",
+ "ownership_ref": "operation-ownership",
+ "owned": True,
+ },
+ ]
diff --git a/tests/transaction/test_concurrent_lock.py b/tests/transaction/test_concurrent_lock.py
deleted file mode 100644
index a853cb253..000000000
--- a/tests/transaction/test_concurrent_lock.py
+++ /dev/null
@@ -1,103 +0,0 @@
-# Copyright (c) 2026 Beijing Volcano Engine Technology Co., Ltd.
-# SPDX-License-Identifier: AGPL-3.0
-"""Tests for concurrent lock acquisition using real AGFS backend."""
-
-import asyncio
-import uuid
-
-from openviking.storage.transaction.lock_handle import LockHandle
-from openviking.storage.transaction.path_lock import PathLockEngine
-
-
-class TestConcurrentLock:
- async def test_exact_mutual_exclusion_same_path(self, agfs_client, test_dir):
- """两个任务竞争同一路径的 EXACT 锁,均最终成功(串行执行)。"""
- lock = PathLockEngine(agfs_client)
-
- results = {}
-
- async def holder(tx_id):
- tx = LockHandle(id=tx_id)
- ok = await lock.acquire_exact_path(test_dir, tx, timeout=5.0)
- if ok:
- await asyncio.sleep(0.3)
- await lock.release(tx)
- results[tx_id] = ok
-
- await asyncio.gather(
- holder("tx-conc-1"),
- holder("tx-conc-2"),
- )
-
- # Both should eventually succeed (one waits for the other)
- assert results["tx-conc-1"] is True
- assert results["tx-conc-2"] is True
-
- async def test_tree_blocks_concurrent_exact_child(self, agfs_client, test_dir):
- """TreeLock on parent 持锁期间,子目录的 ExactPathLock 被阻塞,释放后成功。"""
- child = f"{test_dir}/child-{uuid.uuid4().hex}"
- agfs_client.mkdir(child)
-
- lock = PathLockEngine(agfs_client)
- parent_acquired = asyncio.Event()
- parent_released = asyncio.Event()
-
- child_result = {}
-
- async def parent_holder():
- tx = LockHandle(id="tx-tree-parent")
- ok = await lock.acquire_tree(test_dir, tx, timeout=5.0)
- assert ok is True
- parent_acquired.set()
- await asyncio.sleep(0.5)
- await lock.release(tx)
- parent_released.set()
-
- async def child_worker():
- await parent_acquired.wait()
- tx = LockHandle(id="tx-tree-child")
- ok = await lock.acquire_exact_path(child, tx, timeout=5.0)
- child_result["ok"] = ok
- child_result["after_release"] = parent_released.is_set()
- if ok:
- await lock.release(tx)
-
- await asyncio.gather(parent_holder(), child_worker())
-
- assert child_result["ok"] is True
- # Child should succeed only after parent released
- assert child_result["after_release"] is True
-
- async def test_exact_child_blocks_concurrent_tree_parent(self, agfs_client, test_dir):
- """ExactPathLock on child 持锁期间,父目录的 TreeLock 被阻塞,释放后成功。"""
- child = f"{test_dir}/child-{uuid.uuid4().hex}"
- agfs_client.mkdir(child)
-
- lock = PathLockEngine(agfs_client)
- child_acquired = asyncio.Event()
- child_released = asyncio.Event()
-
- parent_result = {}
-
- async def child_holder():
- tx = LockHandle(id="tx-rev-child")
- ok = await lock.acquire_exact_path(child, tx, timeout=5.0)
- assert ok is True
- child_acquired.set()
- await asyncio.sleep(0.5)
- await lock.release(tx)
- child_released.set()
-
- async def parent_worker():
- await child_acquired.wait()
- tx = LockHandle(id="tx-rev-parent")
- ok = await lock.acquire_tree(test_dir, tx, timeout=5.0)
- parent_result["ok"] = ok
- parent_result["after_release"] = child_released.is_set()
- if ok:
- await lock.release(tx)
-
- await asyncio.gather(child_holder(), parent_worker())
-
- assert parent_result["ok"] is True
- assert parent_result["after_release"] is True
diff --git a/tests/transaction/test_e2e.py b/tests/transaction/test_e2e.py
deleted file mode 100644
index 0e6dd4453..000000000
--- a/tests/transaction/test_e2e.py
+++ /dev/null
@@ -1,126 +0,0 @@
-# Copyright (c) 2026 Beijing Volcano Engine Technology Co., Ltd.
-# SPDX-License-Identifier: AGPL-3.0
-"""End-to-end lock tests using real AGFS backend.
-
-These tests exercise LockContext -> LockManager -> PathLockEngine -> AGFS,
-verifying the acquire -> operate -> release lifecycle.
-"""
-
-import uuid
-
-import pytest
-
-from openviking.storage.errors import LockAcquisitionError
-from openviking.storage.transaction.lock_context import LockContext
-from openviking.storage.transaction.lock_manager import LockManager
-from openviking.storage.transaction.path_lock import LOCK_FILE_NAME
-
-
-def _lock_file_gone(agfs_client, lock_path: str) -> bool:
- """Return True if the lock file does not exist in AGFS."""
- try:
- agfs_client.stat(lock_path)
- return False
- except Exception:
- return True
-
-
-def lock_manager(agfs_client):
- return LockManager(agfs=agfs_client, lock_timeout=1.0, lock_expire=1.0)
-
-
-class TestLockContextCommit:
- async def test_lock_acquired_and_released(self, agfs_client, lock_manager, test_dir):
- """Lock is held inside the context and released after exit."""
- async with LockContext(lock_manager, [test_dir], lock_mode="exact") as handle:
- lock_path = handle.locks[0]
- token = agfs_client.cat(lock_path)
- assert token is not None
-
- assert _lock_file_gone(agfs_client, lock_path)
-
- async def test_file_persists_after_context(self, agfs_client, lock_manager, test_dir):
- """Files written inside a lock context persist."""
- file_path = f"{test_dir}/committed-file.txt"
-
- async with LockContext(lock_manager, [test_dir], lock_mode="exact"):
- agfs_client.write(file_path, b"committed data")
-
- content = agfs_client.cat(file_path)
- assert content == b"committed data"
-
-
-class TestLockContextException:
- async def test_lock_released_on_exception(self, agfs_client, lock_manager, test_dir):
- """Lock is released even when an exception occurs inside the context."""
- lock_path = ""
-
- with pytest.raises(RuntimeError):
- async with LockContext(lock_manager, [test_dir], lock_mode="exact") as handle:
- lock_path = handle.locks[0]
- token = agfs_client.cat(lock_path)
- assert token is not None
- raise RuntimeError("simulated failure")
-
- assert lock_path
- assert _lock_file_gone(agfs_client, lock_path)
-
- async def test_exception_not_swallowed(self, agfs_client, lock_manager, test_dir):
- """Exceptions propagate through the context manager."""
- with pytest.raises(ValueError, match="test error"):
- async with LockContext(lock_manager, [test_dir], lock_mode="exact"):
- raise ValueError("test error")
-
-
-class TestLockContextMv:
- async def test_mv_lock_acquires_both_paths(self, agfs_client, lock_manager, test_dir):
- """mv lock mode acquires tree source and exact destination locks."""
- src = f"{test_dir}/mv-src-{uuid.uuid4().hex}"
- dst = f"{test_dir}/mv-dst-{uuid.uuid4().hex}"
- agfs_client.mkdir(src)
- agfs_client.mkdir(dst)
-
- async with LockContext(lock_manager, [src], lock_mode="mv", mv_dst_path=dst):
- src_token = agfs_client.cat(f"{src}/{LOCK_FILE_NAME}")
- dst_token = agfs_client.cat(f"{dst}/{LOCK_FILE_NAME}")
- src_token_str = src_token.decode("utf-8") if isinstance(src_token, bytes) else src_token
- dst_token_str = dst_token.decode("utf-8") if isinstance(dst_token, bytes) else dst_token
- assert ":T" in src_token_str
- assert ":E" in dst_token_str
-
- for path in [f"{src}/{LOCK_FILE_NAME}", f"{dst}/{LOCK_FILE_NAME}"]:
- assert _lock_file_gone(agfs_client, path)
-
-
-class TestLockContextTree:
- async def test_tree_lock_and_release(self, agfs_client, lock_manager, test_dir):
- """Tree lock is acquired and released."""
- target = f"{test_dir}/tree-{uuid.uuid4().hex}"
- agfs_client.mkdir(target)
-
- async with LockContext(lock_manager, [target], lock_mode="tree"):
- token = agfs_client.cat(f"{target}/{LOCK_FILE_NAME}")
- token_str = token.decode("utf-8") if isinstance(token, bytes) else token
- assert ":T" in token_str
-
- assert _lock_file_gone(agfs_client, f"{target}/{LOCK_FILE_NAME}")
-
-
-class TestSequentialLocks:
- async def test_sequential_locks_on_same_path(self, agfs_client, lock_manager, test_dir):
- """Multiple sequential lock contexts on the same path succeed."""
- for i in range(3):
- async with LockContext(lock_manager, [test_dir], lock_mode="exact"):
- agfs_client.write(f"{test_dir}/f{i}.txt", f"data-{i}".encode())
-
- for i in range(3):
- content = agfs_client.cat(f"{test_dir}/f{i}.txt")
- assert content == f"data-{i}".encode()
-
- async def test_lock_acquisition_failure(self, agfs_client, lock_manager, test_dir):
- """LockContext raises LockAcquisitionError for unsupported lock mode."""
- nonexistent = f"{test_dir}/nonexistent-{uuid.uuid4().hex}"
- with pytest.raises(LockAcquisitionError):
- async with LockContext(lock_manager, [nonexistent], lock_mode="unknown"):
- pass
diff --git a/tests/transaction/test_exact_path_lock.py b/tests/transaction/test_exact_path_lock.py
deleted file mode 100644
index e5f1b63f3..000000000
--- a/tests/transaction/test_exact_path_lock.py
+++ /dev/null
@@ -1,244 +0,0 @@
-# Copyright (c) 2026 Beijing Volcano Engine Technology Co., Ltd.
-# SPDX-License-Identifier: AGPL-3.0
-"""Tests for ExactPathLock semantics."""
-
-import asyncio
-import threading
-
-import pytest
-
-from openviking.storage.transaction.lock_handle import LockHandle
-from openviking.storage.transaction.lock_manager import LockManager
-from openviking.storage.transaction.path_lock import EXACT_LOCK_FILE_PREFIX, PathLockEngine
-
-
-class _MemoryAgfs:
- def __init__(self):
- self.dirs = {"/"}
- self.files: dict[str, bytes] = {}
-
- def _parent(self, path: str) -> str:
- path = path.rstrip("/")
- if "/" not in path:
- return "/"
- parent = path.rsplit("/", 1)[0]
- return parent or "/"
-
- def stat(self, path: str):
- path = path.rstrip("/") or "/"
- if path in self.dirs:
- return {"name": path.rsplit("/", 1)[-1], "isDir": True}
- if path in self.files:
- return {"name": path.rsplit("/", 1)[-1], "isDir": False}
- raise FileNotFoundError(path)
-
- def mkdir(self, path: str):
- path = path.rstrip("/") or "/"
- parent = self._parent(path)
- if parent not in self.dirs:
- raise FileNotFoundError(parent)
- self.dirs.add(path)
- return {"message": "created"}
-
- def read(self, path: str):
- if path not in self.files:
- raise FileNotFoundError(path)
- return self.files[path]
-
- def write(self, path: str, data: bytes):
- parent = self._parent(path)
- if parent not in self.dirs:
- raise FileNotFoundError(parent)
- self.files[path] = data
- return path
-
- def rm(self, path: str, recursive: bool = False):
- path = path.rstrip("/") or "/"
- self.files.pop(path, None)
- if path in self.dirs:
- children = [
- item
- for item in [*self.dirs, *self.files]
- if item != path and item.startswith(path.rstrip("/") + "/")
- ]
- if children and not recursive:
- raise RuntimeError("directory not empty")
- for child in children:
- self.files.pop(child, None)
- self.dirs.discard(child)
- self.dirs.discard(path)
- return {"message": "deleted"}
-
- def ls(self, path: str):
- path = path.rstrip("/") or "/"
- prefix = path.rstrip("/") + "/"
- names: dict[str, bool] = {}
- for item in self.dirs:
- if item == path or not item.startswith(prefix):
- continue
- rest = item[len(prefix) :]
- if "/" not in rest:
- names[rest] = True
- for item in self.files:
- if not item.startswith(prefix):
- continue
- rest = item[len(prefix) :]
- if "/" not in rest:
- names[rest] = False
- return [{"name": name, "isDir": is_dir} for name, is_dir in names.items()]
-
-
-class _ConcurrentParentCreationAgfs(_MemoryAgfs):
- def __init__(self, shared_parent: str):
- super().__init__()
- self.shared_parent = shared_parent
- self._initial_stat_barrier = threading.Barrier(2)
- self._state_lock = threading.Lock()
- self._missing_stat_count = 0
- self.mkdir_attempts = 0
-
- def stat(self, path: str):
- path = path.rstrip("/") or "/"
- should_report_missing = False
- if path == self.shared_parent:
- with self._state_lock:
- if self._missing_stat_count < 2:
- self._missing_stat_count += 1
- should_report_missing = True
- if should_report_missing:
- self._initial_stat_barrier.wait(timeout=5)
- raise FileNotFoundError(path)
- return super().stat(path)
-
- def mkdir(self, path: str):
- path = path.rstrip("/") or "/"
- if path != self.shared_parent:
- return super().mkdir(path)
- with self._state_lock:
- self.mkdir_attempts += 1
- if path in self.dirs:
- raise FileExistsError(path)
- parent = self._parent(path)
- if parent not in self.dirs:
- raise FileNotFoundError(parent)
- self.dirs.add(path)
- return {"message": "created"}
-
-
-def _agfs_with_docs_dir() -> _MemoryAgfs:
- agfs = _MemoryAgfs()
- agfs.mkdir("/local")
- agfs.mkdir("/local/default")
- agfs.mkdir("/local/default/resources")
- agfs.mkdir("/local/default/resources/docs")
- return agfs
-
-
-async def test_exact_path_lock_allows_sibling_paths():
- agfs = _agfs_with_docs_dir()
- lock = PathLockEngine(agfs)
- first = LockHandle(id="exact-a")
- second = LockHandle(id="exact-b")
-
- assert await lock.acquire_exact_path("/local/default/resources/docs/a.md", first)
- assert await lock.acquire_exact_path("/local/default/resources/docs/b.md", second)
-
- await lock.release(first)
- await lock.release(second)
-
-
-async def test_exact_path_locks_tolerate_concurrent_parent_creation():
- shared_parent = "/local/default/resources/shared"
- agfs = _ConcurrentParentCreationAgfs(shared_parent)
- agfs.mkdir("/local")
- agfs.mkdir("/local/default")
- agfs.mkdir("/local/default/resources")
- lock = PathLockEngine(agfs)
- first = LockHandle(id="exact-a")
- second = LockHandle(id="exact-b")
-
- acquired = await asyncio.gather(
- lock.acquire_exact_path(f"{shared_parent}/a.md", first),
- lock.acquire_exact_path(f"{shared_parent}/b.md", second),
- )
-
- assert acquired == [True, True]
- assert agfs.mkdir_attempts == 2
- exact_lock_paths = [
- path
- for path in agfs.files
- if path.startswith(f"{shared_parent}/")
- and path.rsplit("/", 1)[-1].startswith(EXACT_LOCK_FILE_PREFIX)
- ]
- assert len(exact_lock_paths) == 2
-
- await lock.release(first)
- await lock.release(second)
-
-
-async def test_exact_path_lock_blocks_same_path_without_creating_target():
- agfs = _agfs_with_docs_dir()
- lock = PathLockEngine(agfs)
- first = LockHandle(id="exact-a")
- second = LockHandle(id="exact-a-blocked")
- target = "/local/default/resources/docs/a.md"
-
- assert await lock.acquire_exact_path(target, first)
- assert not await lock.acquire_exact_path(target, second, timeout=0.0)
-
- assert lock.is_locked(target)
- with pytest.raises(FileNotFoundError):
- agfs.stat(target)
- assert any(path.rsplit("/", 1)[-1].startswith(EXACT_LOCK_FILE_PREFIX) for path in agfs.files)
-
- await lock.release(first)
- assert not lock.is_locked(target)
-
-
-async def test_exact_path_lock_conflicts_with_tree_lock():
- agfs = _agfs_with_docs_dir()
- lock = PathLockEngine(agfs)
- exact = LockHandle(id="exact-a")
- tree = LockHandle(id="tree-docs")
- target = "/local/default/resources/docs/a.md"
- docs = "/local/default/resources/docs"
-
- assert await lock.acquire_exact_path(target, exact)
- assert not await lock.acquire_tree(docs, tree, timeout=0.0)
-
- await lock.release(exact)
- assert await lock.acquire_tree(docs, tree, timeout=0.0)
-
- blocked = LockHandle(id="exact-blocked-by-tree")
- assert not await lock.acquire_exact_path(target, blocked, timeout=0.0)
-
- await lock.release(tree)
-
-
-async def test_exact_tree_batch_acquires_exact_and_tree_locks():
- agfs = _agfs_with_docs_dir()
- agfs.mkdir("/local/default/resources/docs/events")
- manager = LockManager(agfs=agfs, lock_timeout=0.0, lock_expire=300.0)
- handle = manager.create_handle()
-
- assert await manager.acquire_exact_tree_batch(
- handle,
- exact_paths=["/local/default/resources/docs/profile.md"],
- tree_paths=["/local/default/resources/docs/events"],
- )
- assert len(handle.locks) == 2
-
- blocked = manager.create_handle()
- assert not await manager.acquire_exact_tree_batch(
- blocked,
- exact_paths=["/local/default/resources/docs/profile.md"],
- tree_paths=[],
- )
-
- await manager.release(handle)
- await manager.release(blocked)
diff --git a/tests/transaction/test_lock_context.py b/tests/transaction/test_lock_context.py
deleted file mode 100644
index a29580caa..000000000
--- a/tests/transaction/test_lock_context.py
+++ /dev/null
@@ -1,110 +0,0 @@
-# Copyright (c) 2026 Beijing Volcano Engine Technology Co., Ltd.
-# SPDX-License-Identifier: AGPL-3.0
-"""Tests for LockContext async context manager."""
-
-import uuid
-
-import pytest
-
-from openviking.storage.errors import LockAcquisitionError
-from openviking.storage.transaction.lock_context import LockContext
-from openviking.storage.transaction.lock_manager import LockManager
-from openviking.storage.transaction.path_lock import LOCK_FILE_NAME
-
-
-def _lock_file_gone(agfs_client, lock_path: str) -> bool:
- try:
- agfs_client.stat(lock_path)
- return False
- except Exception:
- return True
-
-
-def lm(agfs_client):
- return LockManager(agfs=agfs_client, lock_timeout=1.0, lock_expire=1.0)
-
-
-class TestLockContextExact:
- async def test_exact_lock_lifecycle(self, agfs_client, lm, test_dir):
- async with LockContext(lm, [test_dir], lock_mode="exact") as handle:
- assert handle is not None
- lock_path = handle.locks[0]
- token = agfs_client.cat(lock_path)
- assert token is not None
-
- assert _lock_file_gone(agfs_client, lock_path)
-
- async def test_lock_released_on_exception(self, agfs_client, lm, test_dir):
- lock_path = ""
-
- with pytest.raises(RuntimeError):
- async with LockContext(lm, [test_dir], lock_mode="exact") as handle:
- lock_path = handle.locks[0]
- assert agfs_client.cat(lock_path) is not None
- raise RuntimeError("fail")
-
- assert lock_path
- assert _lock_file_gone(agfs_client, lock_path)
-
- async def test_exception_propagates(self, lm, test_dir):
- with pytest.raises(ValueError, match="test"):
- async with LockContext(lm, [test_dir], lock_mode="exact"):
- raise ValueError("test")
-
-
-class TestLockContextTree:
- async def test_tree_lock(self, agfs_client, lm, test_dir):
- async with LockContext(lm, [test_dir], lock_mode="tree"):
- token = agfs_client.cat(f"{test_dir}/{LOCK_FILE_NAME}")
- token_str = token.decode("utf-8") if isinstance(token, bytes) else token
- assert ":T" in token_str
-
-
-class TestLockContextMv:
- async def test_mv_lock(self, agfs_client, lm, test_dir):
- src = f"{test_dir}/src-{uuid.uuid4().hex}"
- dst = f"{test_dir}/dst-{uuid.uuid4().hex}"
- agfs_client.mkdir(src)
- agfs_client.mkdir(dst)
-
- async with LockContext(lm, [src], lock_mode="mv", mv_dst_path=dst) as handle:
- assert len(handle.locks) == 2
-
-
-class TestLockContextFailure:
- async def test_unsupported_lock_mode_raises(self, lm):
- with pytest.raises(LockAcquisitionError):
- async with LockContext(lm, ["/local/nonexistent-xyz"], lock_mode="unknown"):
- pass
-
- async def test_handle_cleaned_up_on_failure(self, lm):
- with pytest.raises(LockAcquisitionError):
- async with LockContext(lm, ["/local/nonexistent-xyz"], lock_mode="unknown"):
- pass
-
- assert len(await lm.get_active_handles_async()) == 0
-
-
-class TestLockContextExternalHandle:
- async def test_external_handle_reuses_existing_tree_lock(self, agfs_client, lm, test_dir):
- lock_path = f"{test_dir}/{LOCK_FILE_NAME}"
-
- async with LockContext(lm, [test_dir], lock_mode="tree") as handle:
- before = agfs_client.cat(lock_path)
- before_token = before.decode("utf-8") if isinstance(before, bytes) else before
- assert ":T" in before_token
-
- async with LockContext(lm, [test_dir], lock_mode="exact", handle=handle):
- current = agfs_client.cat(lock_path)
- current_token = current.decode("utf-8") if isinstance(current, bytes) else current
- assert current_token == before_token
- assert ":T" in current_token
-
- still_owned = agfs_client.cat(lock_path)
- still_owned_token = (
- still_owned.decode("utf-8") if isinstance(still_owned, bytes) else still_owned
- )
- assert still_owned_token == before_token
-
- assert _lock_file_gone(agfs_client, lock_path)
diff --git a/tests/transaction/test_lock_manager.py b/tests/transaction/test_lock_manager.py
deleted file mode 100644
index 209e9a816..000000000
--- a/tests/transaction/test_lock_manager.py
+++ /dev/null
@@ -1,132 +0,0 @@
-# Copyright (c) 2026 Beijing Volcano Engine Technology Co., Ltd.
-# SPDX-License-Identifier: AGPL-3.0
-"""Tests for LockManager."""
-
-import asyncio
-import uuid
-from unittest.mock import AsyncMock, MagicMock
-
-import pytest
-
-from openviking.storage.transaction.lock_manager import LockManager
-from openviking.storage.transaction.path_lock import LOCK_FILE_NAME
-
-
-def _lock_file_gone(agfs_client, lock_path: str) -> bool:
- try:
- agfs_client.stat(lock_path)
- return False
- except Exception:
- return True
-
-
-def lm(agfs_client):
- return LockManager(agfs=agfs_client, lock_timeout=1.0, lock_expire=1.0)
-
-
-class TestLockManagerBasic:
- async def test_create_handle_and_acquire_exact_path(self, agfs_client, lm, test_dir):
- handle = lm.create_handle()
- ok = await lm.acquire_exact_path(handle, test_dir)
- assert ok is True
-
- lock_path = handle.locks[0]
- content = agfs_client.cat(lock_path)
- assert content is not None
-
- await lm.release(handle)
- assert _lock_file_gone(agfs_client, lock_path)
-
- async def test_acquire_tree(self, agfs_client, lm, test_dir):
- handle = lm.create_handle()
- ok = await lm.acquire_tree(handle, test_dir)
- assert ok is True
-
- token = agfs_client.cat(f"{test_dir}/{LOCK_FILE_NAME}")
- token_str = token.decode("utf-8") if isinstance(token, bytes) else token
- assert ":T" in token_str
-
- await lm.release(handle)
-
- async def test_acquire_mv(self, agfs_client, lm, test_dir):
- src = f"{test_dir}/mv-src-{uuid.uuid4().hex}"
- dst = f"{test_dir}/mv-dst-{uuid.uuid4().hex}"
- agfs_client.mkdir(src)
- agfs_client.mkdir(dst)
-
- handle = lm.create_handle()
- ok = await lm.acquire_mv(handle, src, dst)
- assert ok is True
- assert len(handle.locks) == 2
-
- await lm.release(handle)
- assert handle.id not in await lm.get_active_handles_async()
-
- async def test_release_removes_from_active(self, lm, test_dir):
- handle = lm.create_handle()
-
- await lm.acquire_exact_path(handle, test_dir)
- assert handle.id in await lm.get_active_handles_async()
-
- await lm.release(handle)
-
- assert handle.id not in await lm.get_active_handles_async()
-
- async def test_stop_releases_all(self, agfs_client, lm, test_dir):
- h1 = lm.create_handle()
- h2 = lm.create_handle()
- await lm.acquire_exact_path(h1, test_dir)
-
- sub = f"{test_dir}/sub-{uuid.uuid4().hex}"
- agfs_client.mkdir(sub)
- await lm.acquire_exact_path(h2, sub)
-
- await lm.stop()
- assert len(await lm.get_active_handles_async()) == 0
-
- async def test_exact_path_allows_missing_target(self, lm):
- handle = lm.create_handle()
- ok = await lm.acquire_exact_path(handle, "/local/nonexistent-xyz")
- assert ok is True
-
- await lm.release(handle)
-
- async def test_explicit_none_timeout_passes_through_as_infinite_wait(self, lm):
- handle = lm.create_handle()
- lm._path_lock = MagicMock()
- lm._path_lock.acquire_tree = AsyncMock(return_value=True)
-
- ok = await lm.acquire_tree(handle, "/local/test", timeout=None)
-
- assert ok is True
- lm._path_lock.acquire_tree.assert_awaited_once_with("/local/test", handle, timeout=None)
-
- async def test_recover_pending_redo_preserves_cancelled_error(self, lm):
- lm._redo_log = MagicMock()
- lm._redo_log.list_pending_async = AsyncMock(return_value=["redo-task"])
- lm._redo_log.read_async = AsyncMock(return_value={"archive_uri": "a", "session_uri": "b"})
- lm._redo_log.mark_done_async = AsyncMock()
- lm._redo_session_memory = AsyncMock(side_effect=asyncio.CancelledError("shutdown"))
-
- with pytest.raises(asyncio.CancelledError):
- await lm._recover_pending_redo()
-
- lm._redo_log.mark_done_async.assert_not_awaited()
-
- async def test_start_skips_redo_recovery_when_disabled(self, client):
- lm_disabled = LockManager(
- agfs=client._client.service._agfs_client,
- lock_timeout=1.0,
- lock_expire=1.0,
- redo_recovery_enabled=False,
- )
- lm_disabled._recover_pending_redo = AsyncMock()
-
- await lm_disabled.start()
- await asyncio.sleep(0)
-
- assert lm_disabled._redo_task is None
- lm_disabled._recover_pending_redo.assert_not_called()
-
- await lm_disabled.stop()
diff --git a/tests/transaction/test_lock_manager_staleness.py b/tests/transaction/test_lock_manager_staleness.py
deleted file mode 100644
index 92dd87f5c..000000000
--- a/tests/transaction/test_lock_manager_staleness.py
+++ /dev/null
@@ -1,80 +0,0 @@
-# Copyright (c) 2026 Beijing Volcano Engine Technology Co., Ltd.
-# SPDX-License-Identifier: AGPL-3.0
-"""Unit tests for LockManager staleness tracking."""
-
-from unittest.mock import AsyncMock, MagicMock
-
-from openviking.storage.transaction.lock_manager import LockManager
-from openviking.storage.transaction.path_lock import LockRefreshResult
-
-
-async def test_refresh_lock_updates_last_active_without_changing_created_at(monkeypatch):
- lm = LockManager(agfs=MagicMock(), lock_expire=300.0)
- handle = lm.create_handle()
- handle.created_at = 100.0
- handle.last_active_at = 100.0
- handle.add_lock("/local/tx/.path.ovlock")
- lm._path_lock.collect_lost_owner_locks = lambda owner: []
- lm._path_lock.collect_lost_owner_locks_async = AsyncMock(return_value=[])
- lm._path_lock.refresh = AsyncMock(
- return_value=LockRefreshResult(refreshed_paths=["/local/tx/.path.ovlock"])
- )
-
- monkeypatch.setattr("openviking.storage.transaction.lock_manager.time.time", lambda: 250.0)
-
- await lm.refresh_lock(handle)
-
- lm._path_lock.refresh.assert_awaited_once_with(handle)
- assert handle.created_at == 100.0
- assert handle.last_active_at == 250.0
-
-
-async def test_stale_cleanup_releases_only_inactive_handles(monkeypatch):
- lm = LockManager(agfs=MagicMock(), lock_expire=300.0)
-
- active_handle = lm.create_handle()
- active_handle.created_at = 0.0
- active_handle.last_active_at = 200.0
- active_handle.add_lock("/local/active/.path.ovlock")
-
- stale_handle = lm.create_handle()
- stale_handle.created_at = 0.0
- stale_handle.last_active_at = 0.0
- stale_handle.add_lock("/local/stale/.path.ovlock")
-
- unlocked_handle = lm.create_handle()
- unlocked_handle.created_at = 0.0
- unlocked_handle.last_active_at = 0.0
-
- released = []
-
- async def fake_sleep(_seconds):
- lm._running = False
-
- async def fake_release(handle):
- released.append(handle.id)
- lm._handles.pop(handle.id, None)
-
- monkeypatch.setattr("openviking.storage.transaction.lock_manager.asyncio.sleep", fake_sleep)
- monkeypatch.setattr("openviking.storage.transaction.lock_manager.time.time", lambda: 400.0)
- monkeypatch.setattr(lm, "release", fake_release)
- lm._path_lock.collect_lost_owner_locks = lambda owner: []
- lm._path_lock.collect_lost_owner_locks_async = AsyncMock(return_value=[])
-
- lm._running = True
- await lm._stale_cleanup_loop()
-
- assert released == [stale_handle.id]
- active_handles = await lm.get_active_handles_async()
- assert active_handle.id in active_handles
- assert unlocked_handle.id not in active_handles
-
-
-def test_get_handle_returns_none_when_lock_ownership_is_lost():
- lm = LockManager(agfs=MagicMock(), lock_expire=300.0)
- handle = lm.create_handle()
- handle.add_lock("/local/stale/.path.ovlock")
- lm._path_lock.collect_lost_owner_locks = lambda owner: list(owner.locks)
-
- assert lm.get_handle(handle.id) is None
- assert handle.id not in lm.get_active_handles()
diff --git a/tests/transaction/test_lock_reentrancy_unit.py b/tests/transaction/test_lock_reentrancy_unit.py
deleted file mode 100644
index 39986e732..000000000
--- a/tests/transaction/test_lock_reentrancy_unit.py
+++ /dev/null
@@ -1,141 +0,0 @@
-# Copyright (c) 2026 Beijing Volcano Engine Technology Co., Ltd.
-# SPDX-License-Identifier: AGPL-3.0
-
-from __future__ import annotations
-
-import os
-
-import pytest
-
-from openviking.storage.transaction.lock_context import LockContext
-from openviking.storage.transaction.lock_manager import LockManager
-from openviking.storage.transaction.path_lock import LOCK_FILE_NAME, PathLockEngine
-
-
-class _FakeAGFS:
- def __init__(self):
- self._dirs = {"/"}
- self._files = {}
-
- def stat(self, path: str):
- if path in self._dirs:
- return {"isDir": True}
- if path in self._files:
- return {"isDir": False}
- raise FileNotFoundError(path)
-
- def mkdir(self, path: str):
- current = ""
- for part in path.split("/"):
- if not part:
- current = "/"
- continue
- current = os.path.join(current, part) if current != "/" else f"/{part}"
- self._dirs.add(current)
-
- def write(self, path: str, data: bytes):
- parent = os.path.dirname(path) or "/"
- self.mkdir(parent)
- self._files[path] = data
-
- def read(self, path: str):
- if path not in self._files:
- raise FileNotFoundError(path)
- return self._files[path]
-
- def rm(self, path: str, recursive: bool = False):
- if path in self._files:
- self._files.pop(path, None)
- return
- if path not in self._dirs:
- raise FileNotFoundError(path)
- prefix = path.rstrip("/") + "/"
- has_children = any(
- child.startswith(prefix)
- for child in self._dirs | set(self._files.keys())
- if child != path
- )
- if has_children and not recursive:
- raise OSError("directory not empty")
- for child in list(self._files.keys()):
- if child.startswith(prefix):
- self._files.pop(child, None)
- for child in sorted(self._dirs, reverse=True):
- if child == path or child.startswith(prefix):
- self._dirs.discard(child)
-
- def ls(self, path: str):
- if path not in self._dirs:
- raise FileNotFoundError(path)
- prefix = path.rstrip("/") + "/"
- children = {}
- for child in self._dirs:
- if not child.startswith(prefix) or child == path:
- continue
- rest = child[len(prefix) :]
- if "/" in rest or not rest:
- continue
- children[rest] = {"name": rest, "isDir": True}
- for child in self._files:
- if not child.startswith(prefix):
- continue
- rest = child[len(prefix) :]
- if "/" in rest or not rest:
- continue
- children[rest] = {"name": rest, "isDir": False}
- return list(children.values())
-
-
-async def test_path_lock_reuses_same_owner_tree_without_overwriting_token():
- agfs = _FakeAGFS()
- agfs.mkdir("/root")
- lock = PathLockEngine(agfs)
- handle = LockManager(agfs).create_handle()
-
- assert await lock.acquire_tree("/root", handle, timeout=0.1) is True
- lock_path = f"/root/{LOCK_FILE_NAME}"
- before = agfs.read(lock_path).decode("utf-8")
- assert before.endswith(":T")
-
- assert await lock.acquire_exact_path("/root", handle, timeout=0.1) is True
- after = agfs.read(lock_path).decode("utf-8")
- assert after == before
- assert after.endswith(":T")
-
-
-async def test_path_lock_reuses_ancestor_tree_without_creating_child_lock():
- agfs = _FakeAGFS()
- agfs.mkdir("/root")
- agfs.mkdir("/root/child")
- lock = PathLockEngine(agfs)
- handle = LockManager(agfs).create_handle()
-
- assert await lock.acquire_tree("/root", handle, timeout=0.1) is True
- assert await lock.acquire_exact_path("/root/child", handle, timeout=0.1) is True
-
- with pytest.raises(FileNotFoundError):
- agfs.read(f"/root/child/{LOCK_FILE_NAME}")
-
-
-async def test_lock_context_with_external_handle_keeps_outer_tree_lock():
- agfs = _FakeAGFS()
- agfs.mkdir("/root")
- lm = LockManager(agfs=agfs, lock_timeout=0.1, lock_expire=60.0)
- lock_path = f"/root/{LOCK_FILE_NAME}"
-
- async with LockContext(lm, ["/root"], lock_mode="tree") as handle:
- before = agfs.read(lock_path).decode("utf-8")
- assert before.endswith(":T")
-
- async with LockContext(lm, ["/root"], lock_mode="exact", handle=handle):
- current = agfs.read(lock_path).decode("utf-8")
- assert current == before
-
- still_owned = agfs.read(lock_path).decode("utf-8")
- assert still_owned == before
-
- with pytest.raises(FileNotFoundError):
- agfs.read(lock_path)
diff --git a/tests/transaction/test_path_lock.py b/tests/transaction/test_path_lock.py
deleted file mode 100644
index fd2dd2a75..000000000
--- a/tests/transaction/test_path_lock.py
+++ /dev/null
@@ -1,689 +0,0 @@
-# Copyright (c) 2026 Beijing Volcano Engine Technology Co., Ltd.
-# SPDX-License-Identifier: AGPL-3.0
-"""Tests for path lock with fencing tokens."""
-
-import time
-from unittest.mock import AsyncMock, MagicMock
-
-from openviking.storage.transaction import path_lock as path_lock_module
-from openviking.storage.transaction.lock_handle import LockHandle
-from openviking.storage.transaction.path_lock import (
- EXACT_LOCK_FILE_PREFIX,
- LOCK_FILE_NAME,
- LOCK_TYPE_EXACT,
- LOCK_TYPE_TREE,
- PathLockEngine,
- _make_fencing_token,
- _parse_fencing_token,
-)
-
-
-def _single_lock_path(handle: LockHandle) -> str:
- assert len(handle.locks) == 1
- return handle.locks[0]
-
-
-class TestFencingToken:
- def test_make_parse_roundtrip(self):
- token = _make_fencing_token("tx-123")
- tx_id, ts, lock_type = _parse_fencing_token(token)
- assert tx_id == "tx-123"
- assert ts > 0
- assert lock_type == LOCK_TYPE_EXACT
-
- def test_make_parse_tree_roundtrip(self):
- token = _make_fencing_token("tx-456", LOCK_TYPE_TREE)
- tx_id, ts, lock_type = _parse_fencing_token(token)
- assert tx_id == "tx-456"
- assert ts > 0
- assert lock_type == LOCK_TYPE_TREE
-
- def test_parse_previous_tree_tokens(self):
- for previous_type in ("P", "S"):
- tx_id, ts, lock_type = _parse_fencing_token(f"tx-old:123:{previous_type}")
- assert tx_id == "tx-old"
- assert ts == 123
- assert lock_type == LOCK_TYPE_TREE
-
- def test_parse_untyped_token_defaults_to_stale_exact(self):
- """Untyped tokens are treated as stale EXACT locks."""
- tx_id, ts, lock_type = _parse_fencing_token("tx-old:1234567890")
- assert tx_id == "tx-old:1234567890"
- assert ts == 0
- assert lock_type == LOCK_TYPE_EXACT
-
- def test_parse_plain_token_defaults_to_exact(self):
- """Plain tx_id (no colon) defaults to ts=0, lock_type=EXACT."""
- tx_id, ts, lock_type = _parse_fencing_token("tx-bare")
- assert tx_id == "tx-bare"
- assert ts == 0
- assert lock_type == LOCK_TYPE_EXACT
-
- def test_tokens_are_unique(self):
- t1 = _make_fencing_token("tx-1")
- time.sleep(0.001)
- t2 = _make_fencing_token("tx-1")
- assert t1 != t2
-
-
-class TestPathLockStale:
- def test_is_lock_stale_no_file(self):
- agfs = MagicMock()
- agfs.read.side_effect = Exception("not found")
- lock = PathLockEngine(agfs)
- assert lock.is_lock_stale("/test/.path.ovlock") is True
-
- def test_is_lock_stale_for_plain_token(self):
- agfs = MagicMock()
- agfs.read.return_value = b"tx-old-format"
- lock = PathLockEngine(agfs)
- assert lock.is_lock_stale("/test/.path.ovlock") is True
-
- def test_is_lock_stale_recent_token(self):
- agfs = MagicMock()
- token = _make_fencing_token("tx-1")
- agfs.read.return_value = token.encode("utf-8")
- lock = PathLockEngine(agfs)
- assert lock.is_lock_stale("/test/.path.ovlock", expire_seconds=300.0) is False
-
-
-class TestPathLockIsLocked:
- def _agfs_with_locks(self, locks: dict[str, bytes]) -> MagicMock:
- """Build an AGFS mock that only returns content for paths in *locks*."""
- agfs = MagicMock()
-
- def _read(p):
- if p in locks:
- return locks[p]
- raise Exception("not found")
-
- agfs.read.side_effect = _read
- return agfs
-
- def test_is_locked_no_lock(self):
- agfs = self._agfs_with_locks({})
- lock = PathLockEngine(agfs)
- assert lock.is_locked("/local/u/foo") is False
-
- def test_is_locked_self_exact_lock(self):
- token = _make_fencing_token("tx-1", LOCK_TYPE_EXACT)
- agfs = self._agfs_with_locks({"/local/u/foo/.path.ovlock": token.encode("utf-8")})
- lock = PathLockEngine(agfs)
- assert lock.is_locked("/local/u/foo") is True
-
- def test_is_locked_ancestor_tree_lock(self):
- token = _make_fencing_token("tx-1", LOCK_TYPE_TREE)
- agfs = self._agfs_with_locks({"/local/u/.path.ovlock": token.encode("utf-8")})
- lock = PathLockEngine(agfs)
- assert lock.is_locked("/local/u/foo/bar") is True
-
- def test_is_locked_ancestor_exact_lock_does_not_propagate(self):
- """An ancestor EXACT lock must not affect descendants -- EXACT locks only the path itself."""
- token = _make_fencing_token("tx-1", LOCK_TYPE_EXACT)
- agfs = self._agfs_with_locks({"/local/u/.path.ovlock": token.encode("utf-8")})
- lock = PathLockEngine(agfs)
- assert lock.is_locked("/local/u/foo/bar") is False
-
- def test_is_locked_ignores_stale_by_default(self):
- old_ts = time.time_ns() - int(600 * 1e9) # 600s ago
- stale = f"tx-dead:{old_ts}:{LOCK_TYPE_EXACT}".encode("utf-8")
- agfs = self._agfs_with_locks({"/local/u/foo/.path.ovlock": stale})
- lock = PathLockEngine(agfs, lock_expire=300.0)
- assert lock.is_locked("/local/u/foo") is False
-
- def test_is_locked_can_include_stale(self):
- old_ts = time.time_ns() - int(600 * 1e9)
- stale = f"tx-dead:{old_ts}:{LOCK_TYPE_EXACT}".encode("utf-8")
- agfs = self._agfs_with_locks({"/local/u/foo/.path.ovlock": stale})
- lock = PathLockEngine(agfs, lock_expire=300.0)
- assert lock.is_locked("/local/u/foo", ignore_stale=False) is True
-
- async def test_is_locked_async_uses_async_agfs_path(self):
- token = _make_fencing_token("tx-1", LOCK_TYPE_TREE)
- agfs = self._agfs_with_locks({"/local/u/.path.ovlock": token.encode("utf-8")})
- lock = PathLockEngine(agfs)
-
- assert await lock.is_locked_async("/local/u/foo/bar") is True
-
- def test_is_locked_sync_passes_path_derived_ctx(self):
- token = _make_fencing_token("tx-1", LOCK_TYPE_TREE)
- seen: list[dict[str, str] | None] = []
-
- class _CtxAwareAgfs:
- def read(self, path, *, ctx=None):
- seen.append(ctx)
- if path == "/local/u/.path.ovlock":
- return token.encode("utf-8")
- raise Exception("not found")
-
- def stat(self, path, *, ctx=None):
- seen.append(ctx)
- raise Exception("not found")
-
- lock = PathLockEngine(_CtxAwareAgfs())
-
- assert lock.is_locked("/local/u/foo/bar") is True
- assert {"account_id": "u"} in seen
-
-
-class TestPathLockOwnership:
- async def test_refresh_reports_refreshed_lost_and_failed_paths(self):
- owned_path = "/locks/owned/.path.ovlock"
- lost_path = "/locks/lost/.path.ovlock"
- missing_path = "/locks/missing/.path.ovlock"
- failed_path = "/locks/failed/.path.ovlock"
-
- tokens = {
- owned_path: _make_fencing_token("tx-1", LOCK_TYPE_EXACT),
- lost_path: _make_fencing_token("tx-2", LOCK_TYPE_TREE),
- failed_path: _make_fencing_token("tx-1", LOCK_TYPE_TREE),
- }
- agfs = MagicMock()
-
- def read_side_effect(lock_path):
- if lock_path == missing_path:
- raise FileNotFoundError(lock_path)
- return tokens[lock_path].encode("utf-8")
-
- def write_side_effect(lock_path, content):
- if lock_path == failed_path:
- raise OSError("write failed")
- tokens[lock_path] = content.decode("utf-8")
-
- agfs.read.side_effect = read_side_effect
- agfs.write.side_effect = write_side_effect
-
- lock = PathLockEngine(agfs)
- tx = LockHandle(id="tx-1")
- for lock_path in [owned_path, lost_path, missing_path, failed_path]:
- tx.add_lock(lock_path)
-
- result = await lock.refresh(tx)
-
- assert result.refreshed_paths == [owned_path]
- assert set(result.lost_paths) == {lost_path, missing_path}
- assert result.failed_paths == [failed_path]
-
- async def test_release_skips_locks_no_longer_owned(self):
- owned_path = "/locks/owned/.path.ovlock"
- replaced_path = "/locks/replaced/.path.ovlock"
-
- tokens = {
- owned_path: _make_fencing_token("tx-1", LOCK_TYPE_EXACT),
- replaced_path: _make_fencing_token("tx-2", LOCK_TYPE_EXACT),
- }
- agfs = MagicMock()
- agfs.read.side_effect = lambda lock_path: tokens[lock_path].encode("utf-8")
-
- lock = PathLockEngine(agfs)
- lock._remove_lock_file = AsyncMock(return_value=True)
- tx = LockHandle(id="tx-1")
- tx.add_lock(owned_path)
- tx.add_lock(replaced_path)
-
- await lock.release(tx)
-
- lock._remove_lock_file.assert_awaited_once_with(owned_path)
- assert tx.locks == []
-
-
-class TestPathLockBehavior:
- """Behavioral tests using real AGFS backend."""
-
- async def test_acquire_exact_path_creates_lock_file(self, agfs_client, test_dir):
- lock = PathLockEngine(agfs_client)
- tx = LockHandle(id="tx-exact-1")
-
- ok = await lock.acquire_exact_path(test_dir, tx, timeout=3.0)
- assert ok is True
-
- lock_path = _single_lock_path(tx)
- assert lock_path == f"{test_dir}/{LOCK_FILE_NAME}"
- content = agfs_client.cat(lock_path)
- token = content.decode("utf-8") if isinstance(content, bytes) else content
- assert ":E" in token
- assert "tx-exact-1" in token
-
- await lock.release(tx)
-
- async def test_acquire_tree_creates_lock_file(self, agfs_client, test_dir):
- lock = PathLockEngine(agfs_client)
- tx = LockHandle(id="tx-tree-1")
-
- ok = await lock.acquire_tree(test_dir, tx, timeout=3.0)
- assert ok is True
-
- lock_path = f"{test_dir}/{LOCK_FILE_NAME}"
- content = agfs_client.cat(lock_path)
- token = content.decode("utf-8") if isinstance(content, bytes) else content
- assert ":T" in token
- assert "tx-tree-1" in token
-
- await lock.release(tx)
-
- async def test_acquire_tree_existing_file_uses_parent_sidecar_lock(self, agfs_client, test_dir):
- lock = PathLockEngine(agfs_client)
- tx = LockHandle(id="tx-tree-file")
- file_path = f"{test_dir}/profile.md"
- agfs_client.write(file_path, b"# Profile\n")
-
- ok = await lock.acquire_tree(file_path, tx, timeout=3.0)
- assert ok is True
-
- lock_path = _single_lock_path(tx)
- assert lock_path.startswith(f"{test_dir}/{EXACT_LOCK_FILE_PREFIX}profile.md.")
- assert lock_path != f"{file_path}/{LOCK_FILE_NAME}"
- content = agfs_client.cat(lock_path)
- token = content.decode("utf-8") if isinstance(content, bytes) else content
- assert ":T" in token
- assert "tx-tree-file" in token
-
- await lock.release(tx)
- try:
- agfs_client.stat(lock_path)
- raise AssertionError("file tree lock should have been removed")
- except AssertionError:
- raise
- except Exception:
- pass
-
- async def test_acquire_tree_existing_file_sidecar_sanitizes_name(self, agfs_client, test_dir):
- lock = PathLockEngine(agfs_client)
- tx = LockHandle(id="tx-tree-file-special")
- file_path = f"{test_dir}/profile with spaces \u4e2d.md"
- agfs_client.write(file_path, b"# Profile\n")
-
- ok = await lock.acquire_tree(file_path, tx, timeout=3.0)
- assert ok is True
-
- lock_path = _single_lock_path(tx)
- assert lock_path.startswith(f"{test_dir}/{EXACT_LOCK_FILE_PREFIX}profile_with_spaces")
- assert lock_path.endswith(lock._get_prefixed_exact_lock_path(file_path).rsplit(".", 1)[-1])
- content = agfs_client.cat(lock_path)
- token = content.decode("utf-8") if isinstance(content, bytes) else content
- assert ":T" in token
-
- await lock.release(tx)
-
- async def test_acquire_tree_existing_file_blocks_second_owner_until_release(
- self, agfs_client, test_dir
- ):
- lock = PathLockEngine(agfs_client)
- tx1 = LockHandle(id="tx-tree-file-hold")
- tx2 = LockHandle(id="tx-tree-file-wait")
- file_path = f"{test_dir}/blocked.md"
- agfs_client.write(file_path, b"# Blocked\n")
-
- assert await lock.acquire_tree(file_path, tx1, timeout=3.0) is True
- assert await lock.acquire_tree(file_path, tx2, timeout=0.0) is False
-
- await lock.release(tx1)
-
- assert await lock.acquire_tree(file_path, tx2, timeout=3.0) is True
- await lock.release(tx2)
-
- async def test_acquire_tree_creates_missing_directory_after_conflict_check(
- self, agfs_client, test_dir
- ):
- lock = PathLockEngine(agfs_client)
- tx = LockHandle(id="tx-tree-missing")
- target = f"{test_dir}/new-resource"
-
- ok = await lock.acquire_tree(target, tx, timeout=3.0)
- assert ok is True
- assert _single_lock_path(tx) == f"{target}/{LOCK_FILE_NAME}"
- assert agfs_client.stat(target).get("isDir") is True
-
- await lock.release(tx)
-
- async def test_tree_blocked_by_ancestor_tree_does_not_create_missing_directory(
- self, agfs_client, test_dir
- ):
- lock = PathLockEngine(agfs_client)
- parent = LockHandle(id="tx-parent-tree")
- child = LockHandle(id="tx-child-tree")
- target = f"{test_dir}/blocked-resource"
-
- assert await lock.acquire_tree(test_dir, parent, timeout=3.0) is True
- assert await lock.acquire_tree(target, child, timeout=0.0) is False
-
- try:
- agfs_client.stat(target)
- raise AssertionError("missing TreeLock target should not be created on conflict")
- except AssertionError:
- raise
- except Exception:
- pass
-
- await lock.release(parent)
-
- async def test_fail_fast_tree_conflict_warning_is_throttled(
- self, agfs_client, test_dir, monkeypatch
- ):
- lock = PathLockEngine(agfs_client)
- parent = LockHandle(id="tx-parent-tree")
- child = LockHandle(id="tx-child-tree")
- child_retry = LockHandle(id="tx-child-tree-retry")
- target = f"{test_dir}/blocked-resource"
-
- assert await lock.acquire_tree(test_dir, parent, timeout=3.0) is True
-
- warnings = []
- debug_logs = []
- path_lock_module._last_timeout_warning_at.clear()
- monkeypatch.setattr(path_lock_module.logger, "warning", warnings.append)
- monkeypatch.setattr(path_lock_module.logger, "debug", debug_logs.append)
-
- assert await lock.acquire_tree(target, child, timeout=0.0) is False
- assert await lock.acquire_tree(target, child_retry, timeout=0.0) is False
-
- timeout_warnings = [message for message in warnings if "Timeout waiting" in message]
- assert len(timeout_warnings) == 1
- assert "Timeout waiting for ancestor TREE lock" in timeout_warnings[0]
- assert debug_logs == []
-
- await lock.release(parent)
-
- async def test_acquire_exact_path_allows_missing_target(self, agfs_client):
- lock = PathLockEngine(agfs_client)
- tx = LockHandle(id="tx-no-dir")
-
- ok = await lock.acquire_exact_path("/local/nonexistent-path-xyz", tx, timeout=0.5)
- assert ok is True
- assert len(tx.locks) == 1
- assert tx.locks[0].rsplit("/", 1)[-1].startswith(EXACT_LOCK_FILE_PREFIX)
-
- await lock.release(tx)
-
- async def test_exact_blocked_by_ancestor_tree_does_not_create_missing_parent(
- self, agfs_client, test_dir
- ):
- lock = PathLockEngine(agfs_client)
- parent = LockHandle(id="tx-parent-tree")
- child = LockHandle(id="tx-child-exact")
- missing_parent = f"{test_dir}/blocked-dir"
- target = f"{missing_parent}/file.md"
-
- assert await lock.acquire_tree(test_dir, parent, timeout=3.0) is True
- assert await lock.acquire_exact_path(target, child, timeout=0.0) is False
-
- try:
- agfs_client.stat(missing_parent)
- raise AssertionError("missing exact-lock parent should not be created on conflict")
- except AssertionError:
- raise
- except Exception:
- pass
-
- await lock.release(parent)
-
- async def test_release_removes_lock_file(self, agfs_client, test_dir):
- lock = PathLockEngine(agfs_client)
- tx = LockHandle(id="tx-release-1")
-
- await lock.acquire_exact_path(test_dir, tx, timeout=3.0)
- lock_path = _single_lock_path(tx)
-
- await lock.release(tx)
-
- # Lock file should be gone (use stat, not cat — cat returns b'' for deleted files)
- try:
- agfs_client.stat(lock_path)
- raise AssertionError("Lock file should have been removed")
- except AssertionError:
- raise
- except Exception:
- pass # Expected: file not found
-
- async def test_sequential_acquire_works(self, agfs_client, test_dir):
- lock = PathLockEngine(agfs_client)
-
- tx1 = LockHandle(id="tx-seq-1")
- ok1 = await lock.acquire_exact_path(test_dir, tx1, timeout=3.0)
- assert ok1 is True
-
- await lock.release(tx1)
-
- tx2 = LockHandle(id="tx-seq-2")
- ok2 = await lock.acquire_exact_path(test_dir, tx2, timeout=3.0)
- assert ok2 is True
-
- await lock.release(tx2)
-
- async def test_exact_blocked_by_ancestor_tree(self, agfs_client, test_dir):
- """EXACT on child blocked while ancestor holds TreeLock."""
- import uuid as _uuid
-
- child = f"{test_dir}/child-{_uuid.uuid4().hex}"
- agfs_client.mkdir(child)
-
- lock = PathLockEngine(agfs_client)
- tx_parent = LockHandle(id="tx-parent-tree")
- ok = await lock.acquire_tree(test_dir, tx_parent, timeout=3.0)
- assert ok is True
-
- tx_child = LockHandle(id="tx-child-exact")
- blocked = await lock.acquire_exact_path(child, tx_child, timeout=0.5)
- assert blocked is False
-
- await lock.release(tx_parent)
-
- async def test_tree_blocked_by_descendant_exact(self, agfs_client, test_dir):
- """TreeLock on parent blocked while descendant holds ExactPathLock."""
- import uuid as _uuid
-
- child = f"{test_dir}/child-{_uuid.uuid4().hex}"
- agfs_client.mkdir(child)
-
- lock = PathLockEngine(agfs_client)
- tx_child = LockHandle(id="tx-desc-exact")
- ok = await lock.acquire_exact_path(child, tx_child, timeout=3.0)
- assert ok is True
-
- tx_parent = LockHandle(id="tx-parent-tree")
- blocked = await lock.acquire_tree(test_dir, tx_parent, timeout=0.5)
- assert blocked is False
-
- await lock.release(tx_child)
-
- async def test_acquire_mv_creates_tree_and_exact_locks(self, agfs_client, test_dir):
- """Directory move locks the source tree and exact destination path."""
- import uuid as _uuid
-
- src = f"{test_dir}/src-{_uuid.uuid4().hex}"
- dst = f"{test_dir}/dst-{_uuid.uuid4().hex}"
- agfs_client.mkdir(src)
- agfs_client.mkdir(dst)
-
- lock = PathLockEngine(agfs_client)
- tx = LockHandle(id="tx-mv-1")
- ok = await lock.acquire_mv(src, dst, tx, timeout=3.0)
- assert ok is True
-
- src_token_bytes = agfs_client.cat(f"{src}/{LOCK_FILE_NAME}")
- src_token = (
- src_token_bytes.decode("utf-8")
- if isinstance(src_token_bytes, bytes)
- else src_token_bytes
- )
- assert ":T" in src_token
-
- dst_token_bytes = agfs_client.cat(f"{dst}/{LOCK_FILE_NAME}")
- dst_token = (
- dst_token_bytes.decode("utf-8")
- if isinstance(dst_token_bytes, bytes)
- else dst_token_bytes
- )
- assert ":E" in dst_token
-
- await lock.release(tx)
-
- async def test_exact_does_not_block_sibling_exact(self, agfs_client, test_dir):
- """EXACT locks on different directories do not conflict."""
- import uuid as _uuid
-
- dir_a = f"{test_dir}/sibling-a-{_uuid.uuid4().hex}"
- dir_b = f"{test_dir}/sibling-b-{_uuid.uuid4().hex}"
- agfs_client.mkdir(dir_a)
- agfs_client.mkdir(dir_b)
-
- lock = PathLockEngine(agfs_client)
- tx_a = LockHandle(id="tx-sib-a")
- tx_b = LockHandle(id="tx-sib-b")
-
- ok_a = await lock.acquire_exact_path(dir_a, tx_a, timeout=3.0)
- ok_b = await lock.acquire_exact_path(dir_b, tx_b, timeout=3.0)
-
- assert ok_a is True
- assert ok_b is True
-
- await lock.release(tx_a)
- await lock.release(tx_b)
-
- async def test_stale_lock_auto_removed_on_acquire(self, agfs_client, test_dir):
- """A stale lock (expired fencing token) is auto-removed, allowing a new acquire."""
- import uuid as _uuid
-
- target = f"{test_dir}/stale-{_uuid.uuid4().hex}"
- agfs_client.mkdir(target)
-
- lock = PathLockEngine(agfs_client, lock_expire=300.0)
- lock_path = lock._get_exact_lock_path(target)
-
- # Write a lock file with a very old timestamp (simulate crashed process)
- old_ts = time.time_ns() - int(600 * 1e9) # 600 seconds ago
- stale_token = f"tx-dead:{old_ts}:{LOCK_TYPE_EXACT}"
- agfs_client.write(lock_path, stale_token.encode("utf-8"))
-
- # New transaction should succeed by auto-removing the stale lock
- tx = LockHandle(id="tx-new-owner")
- ok = await lock.acquire_exact_path(target, tx, timeout=2.0)
- assert ok is True
-
- # Verify new lock is owned by our transaction
- content = agfs_client.cat(lock_path)
- token = content.decode("utf-8") if isinstance(content, bytes) else content
- assert "tx-new-owner" in token
-
- await lock.release(tx)
-
- async def test_stale_tree_ancestor_auto_removed(self, agfs_client, test_dir):
- """A stale TreeLock on ancestor is auto-removed when child acquires ExactPathLock."""
- import uuid as _uuid
-
- child = f"{test_dir}/child-stale-{_uuid.uuid4().hex}"
- agfs_client.mkdir(child)
-
- # Write stale TreeLock on parent
- parent_lock = f"{test_dir}/{LOCK_FILE_NAME}"
- old_ts = time.time_ns() - int(600 * 1e9)
- stale_token = f"tx-dead-parent:{old_ts}:{LOCK_TYPE_TREE}"
- agfs_client.write(parent_lock, stale_token.encode("utf-8"))
-
- lock = PathLockEngine(agfs_client, lock_expire=300.0)
- tx = LockHandle(id="tx-child-new")
- ok = await lock.acquire_exact_path(child, tx, timeout=2.0)
- assert ok is True
-
- await lock.release(tx)
- # Clean up stale parent lock if still present
- try:
- agfs_client.rm(parent_lock)
- except Exception:
- pass
-
- async def test_exact_same_path_no_wait_fails_immediately(self, agfs_client, test_dir):
- """With timeout=0, a conflicting lock fails immediately."""
- import uuid as _uuid
-
- target = f"{test_dir}/nowait-{_uuid.uuid4().hex}"
- agfs_client.mkdir(target)
-
- lock = PathLockEngine(agfs_client)
- tx1 = LockHandle(id="tx-hold")
- ok1 = await lock.acquire_exact_path(target, tx1, timeout=3.0)
- assert ok1 is True
-
- # Second acquire with timeout=0 should fail immediately
- tx2 = LockHandle(id="tx-blocked")
- t0 = time.monotonic()
- ok2 = await lock.acquire_exact_path(target, tx2, timeout=0.0)
- elapsed = time.monotonic() - t0
-
- assert ok2 is False
- assert elapsed < 1.0 # Should not wait
-
- await lock.release(tx1)
-
- async def test_tree_same_path_mutual_exclusion(self, agfs_client, test_dir):
- """Two TreeLocks on the same path: second one blocked until first releases."""
- import uuid as _uuid
-
- target = f"{test_dir}/tree-excl-{_uuid.uuid4().hex}"
- agfs_client.mkdir(target)
-
- lock = PathLockEngine(agfs_client)
- tx1 = LockHandle(id="tx-tree1")
- ok1 = await lock.acquire_tree(target, tx1, timeout=3.0)
- assert ok1 is True
-
- tx2 = LockHandle(id="tx-tree2")
- ok2 = await lock.acquire_tree(target, tx2, timeout=0.5)
- assert ok2 is False
-
- await lock.release(tx1)
-
- # Now tx2 should succeed
- ok2_retry = await lock.acquire_tree(target, tx2, timeout=3.0)
- assert ok2_retry is True
- await lock.release(tx2)
-
- async def test_exact_reuses_same_owner_tree_lock_on_same_path(self, agfs_client, test_dir):
- lock = PathLockEngine(agfs_client)
- tx = LockHandle(id="tx-reentrant-same-path")
-
- ok = await lock.acquire_tree(test_dir, tx, timeout=3.0)
- assert ok is True
-
- lock_path = f"{test_dir}/{LOCK_FILE_NAME}"
- before = agfs_client.cat(lock_path)
- before_token = before.decode("utf-8") if isinstance(before, bytes) else before
- assert ":T" in before_token
-
- ok_reuse = await lock.acquire_exact_path(test_dir, tx, timeout=0.5)
- assert ok_reuse is True
-
- after = agfs_client.cat(lock_path)
- after_token = after.decode("utf-8") if isinstance(after, bytes) else after
- assert after_token == before_token
- assert ":T" in after_token
-
- await lock.release(tx)
-
- async def test_exact_under_same_owner_tree_does_not_create_child_lock(
- self, agfs_client, test_dir
- ):
- import uuid as _uuid
-
- child = f"{test_dir}/child-reentrant-{_uuid.uuid4().hex}"
- agfs_client.mkdir(child)
-
- lock = PathLockEngine(agfs_client)
- tx = LockHandle(id="tx-reentrant-child")
-
- ok = await lock.acquire_tree(test_dir, tx, timeout=3.0)
- assert ok is True
-
- ok_child = await lock.acquire_exact_path(child, tx, timeout=0.5)
- assert ok_child is True
-
- child_lock_path = lock._get_exact_lock_path(child)
- try:
- agfs_client.stat(child_lock_path)
- raise AssertionError("child lock should not be created when ancestor tree is owned")
- except AssertionError:
- raise
- except Exception:
- pass
-
- await lock.release(tx)
diff --git a/tests/unit/test_resource_reservation.py b/tests/unit/test_resource_reservation.py
index 9e87a3c3a..a80f7a07e 100644
--- a/tests/unit/test_resource_reservation.py
+++ b/tests/unit/test_resource_reservation.py
@@ -25,10 +25,6 @@ def _make_processor(monkeypatch, *, existing=()):
processor = ResourceProcessor.__new__(ResourceProcessor)
viking_fs = _FakeVikingFS(existing)
monkeypatch.setattr(resource_processor_module, "get_viking_fs", lambda: viking_fs)
- monkeypatch.setattr(
- "openviking.storage.transaction.get_lock_manager",
- lambda: object(),
- )
return processor
diff --git a/tests/utils/test_resource_processor_processing_mode.py b/tests/utils/test_resource_processor_processing_mode.py
index d2b39836c..6c199a7cf 100644
--- a/tests/utils/test_resource_processor_processing_mode.py
+++ b/tests/utils/test_resource_processor_processing_mode.py
@@ -50,6 +50,7 @@ def ctx() -> RequestContext:
@pytest.mark.asyncio
async def test_vectors_only_persists_tree_and_vectorizes_files_only(monkeypatch, ctx):
viking_fs = SimpleNamespace(
+ _async_agfs=SimpleNamespace(pathlock_release=AsyncMock()),
persist_temp_tree=AsyncMock(),
delete_temp=AsyncMock(),
tree=AsyncMock(
@@ -78,7 +79,7 @@ async def test_vectors_only_persists_tree_and_vectorizes_files_only(monkeypatch,
processor._delete_resource_semantic_markers = AsyncMock()
processor._delete_resource_semantic_vectors = AsyncMock()
processor._delete_removed_resource_vectors = AsyncMock()
- lock = SimpleNamespace(active=True, handle="lock-1", close=AsyncMock())
+ lock = {"lease_ref": "lock-1"}
result = await processor.finish_prepared_resource(
{
@@ -96,12 +97,15 @@ async def test_vectors_only_persists_tree_and_vectorizes_files_only(monkeypatch,
assert result == {"status": "success", "root_uri": "viking://resources/demo"}
viking_fs.persist_temp_tree.assert_awaited_once_with(
- "viking://temp/demo", "viking://resources/demo", ctx=ctx
+ "viking://temp/demo",
+ "viking://resources/demo",
+ ctx=ctx,
+ lease_ref=lock,
)
rewrite_image_uris.assert_awaited_once_with(
"viking://resources/demo",
ctx=ctx,
- lock_handle="lock-1",
+ lease_ref=lock,
)
viking_fs.delete_temp.assert_awaited_once_with("tmp/demo", ctx=ctx)
vectorize_file.assert_awaited_once()
@@ -120,12 +124,13 @@ async def test_vectors_only_persists_tree_and_vectorizes_files_only(monkeypatch,
assert vectorize_file.await_args.kwargs["register_request_wait"] is True
processor._delete_resource_semantic_markers.assert_not_awaited()
processor._delete_resource_semantic_vectors.assert_not_awaited()
- lock.close.assert_awaited_once()
+ viking_fs._async_agfs.pathlock_release.assert_awaited_once_with(lock)
@pytest.mark.asyncio
async def test_vectors_only_skips_vectorization_when_build_index_false(monkeypatch, ctx):
viking_fs = SimpleNamespace(
+ _async_agfs=SimpleNamespace(pathlock_release=AsyncMock()),
persist_temp_tree=AsyncMock(),
delete_temp=AsyncMock(),
tree=AsyncMock(return_value=[]),
@@ -137,7 +142,7 @@ async def test_vectors_only_skips_vectorization_when_build_index_false(monkeypat
processor = ResourceProcessor(_FakeVikingDB())
processor._delete_resource_semantic_markers = AsyncMock()
processor._delete_resource_semantic_vectors = AsyncMock()
- lock = SimpleNamespace(active=True, handle="lock-1", close=AsyncMock())
+ lock = {"lease_ref": "lock-1"}
await processor.finish_prepared_resource(
{
@@ -159,6 +164,7 @@ async def test_vectors_only_skips_vectorization_when_build_index_false(monkeypat
@pytest.mark.asyncio
async def test_vectors_only_syncs_preexisting_target_instead_of_merging(monkeypatch, ctx):
viking_fs = SimpleNamespace(
+ _async_agfs=SimpleNamespace(pathlock_release=AsyncMock()),
persist_temp_tree=AsyncMock(),
delete_temp=AsyncMock(),
tree=AsyncMock(return_value=[]),
@@ -174,7 +180,7 @@ async def test_vectors_only_syncs_preexisting_target_instead_of_merging(monkeypa
monkeypatch.setattr("openviking.utils.resource_processor.vectorize_file", AsyncMock())
processor = ResourceProcessor(_FakeVikingDB())
processor._delete_resource_semantic_vectors = AsyncMock()
- lock = SimpleNamespace(active=True, handle="lock-1", close=AsyncMock())
+ lock = {"lease_ref": "lock-1"}
await processor.finish_prepared_resource(
{
@@ -202,6 +208,7 @@ async def test_vectors_only_syncs_preexisting_target_instead_of_merging(monkeypa
@pytest.mark.asyncio
async def test_vectors_only_leaves_existing_semantic_vectors_untouched(monkeypatch, ctx):
viking_fs = SimpleNamespace(
+ _async_agfs=SimpleNamespace(pathlock_release=AsyncMock()),
persist_temp_tree=AsyncMock(),
delete_temp=AsyncMock(),
tree=AsyncMock(return_value=[]),
@@ -212,7 +219,7 @@ async def test_vectors_only_leaves_existing_semantic_vectors_untouched(monkeypat
processor = ResourceProcessor(_FakeVikingDB())
processor._delete_resource_semantic_vectors = AsyncMock()
processor._delete_removed_resource_vectors = AsyncMock()
- lock = SimpleNamespace(active=True, handle="lock-1", close=AsyncMock())
+ lock = {"lease_ref": "lock-1"}
await processor.finish_prepared_resource(
{
@@ -232,6 +239,7 @@ async def test_vectors_only_leaves_existing_semantic_vectors_untouched(monkeypat
@pytest.mark.asyncio
async def test_vectors_only_deletes_sync_removed_detail_vectors(monkeypatch, ctx):
viking_fs = SimpleNamespace(
+ _async_agfs=SimpleNamespace(pathlock_release=AsyncMock()),
persist_temp_tree=AsyncMock(),
delete_temp=AsyncMock(),
tree=AsyncMock(return_value=[]),
@@ -251,7 +259,7 @@ async def test_vectors_only_deletes_sync_removed_detail_vectors(monkeypatch, ctx
processor = ResourceProcessor(_FakeVikingDB())
processor._delete_resource_semantic_vectors = AsyncMock()
processor._delete_removed_resource_vectors = AsyncMock()
- lock = SimpleNamespace(active=True, handle="lock-1", close=AsyncMock())
+ lock = {"lease_ref": "lock-1"}
await processor.finish_prepared_resource(
{