Skip to content

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

Revert "refactor(pathlock):using rust implement instead python (#3557)" (#3597)

baojun-zhang1841dfed8132
diff --git a/Cargo.lock b/Cargo.lock
index 59dffc591..8be5cb555 100644
--- a/Cargo.lock
+++ b/Cargo.lock
@@ -3880,7 +3880,6 @@ dependencies = [
"chrono",
"criterion",
"dashmap",
- "fd-lock",
"flate2",
"futures",
"gix-actor",
@@ -3904,7 +3903,6 @@ 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 042fec626..d10db441c 100644
--- a/crates/ragfs-python/src/lib.rs
+++ b/crates/ragfs-python/src/lib.rs
@@ -8,61 +8,10 @@ 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::{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 std::time::UNIX_EPOCH;
use ragfs::cache::{
CacheError, CacheNamespace, CachePolicy, CacheProvider, CacheResult, CacheTraversalMode,
@@ -70,48 +19,10 @@ use ragfs::cache::{
};
use ragfs::core::builder::EncryptionConfig;
use ragfs::core::{
- build_default_stack, build_stack_with_mountable, ConfigValue, FileInfo, FileSystem,
+ build_default_stack, register_builtin_plugins, ConfigValue, FileInfo, FileSystem,
FilesystemStats, FsContext, FsContextInner, FsOperation, GlobPage, GrepResult, MountableFS,
- OperationStats, PathLockContext, PluginConfig, RagfsConfig, TreeEntry, WriteFlag, FS_CTX,
+ OperationStats, PluginConfig, RagfsConfig, StatsWrappedFS, 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 {
@@ -889,135 +800,11 @@ 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 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())
+ let account_id = ctx
+ .and_then(|m| m.get("account_id").cloned())
+ .unwrap_or_default();
+ Arc::new(FsContextInner::new(account_id))
}
#[derive(serde::Deserialize)]
@@ -1067,8 +854,6 @@ 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 {
@@ -1087,11 +872,6 @@ 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]
@@ -1151,28 +931,6 @@ 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 {
@@ -1199,7 +957,18 @@ impl RAGFSBindingClient {
CacheNamespace::new(&cache_config.namespace),
cache_policy_from_config(&cache_config),
));
- rt.block_on(build_stack_with_mountable(ragfs_cfg, mountable))
+ 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 }
} else {
rt.block_on(build_default_stack(ragfs_cfg))
};
@@ -1220,7 +989,6 @@ impl RAGFSBindingClient {
rt,
git_service,
git_backend,
- pathlock_manager: stack.pathlock_manager,
})
}
@@ -2015,491 +1783,6 @@ 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:
@@ -2568,16 +1851,6 @@ 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 d0190d00a..d23af4e6c 100644
--- a/crates/ragfs/Cargo.toml
+++ b/crates/ragfs/Cargo.toml
@@ -48,7 +48,6 @@ flate2 = "1.0"
# Path handling and filesystem
path-clean = "1.0"
-fd-lock = "4.0.4"
# Data structures
radix_trie = "0.2"
@@ -87,7 +86,6 @@ 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 a0131865c..bbe21a5e7 100644
--- a/crates/ragfs/src/cache/policy.rs
+++ b/crates/ragfs/src/cache/policy.rs
@@ -1,7 +1,5 @@
//! 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.
@@ -137,7 +135,7 @@ impl CachePolicy {
}
let name = normalized.rsplit('/').next().unwrap_or("");
- if is_hidden_runtime_lock_name(name)
+ if name == ".path.ovlock"
|| name.ends_with(".lock")
|| name.ends_with(".lck")
|| matches!(
@@ -181,20 +179,3 @@ 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 2df524d6a..d36151b46 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::CreateNew | WriteFlag::Truncate)
+ && matches!(flags, WriteFlag::Create | 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 da89b1cdc..1cf6f4c5e 100644
--- a/crates/ragfs/src/core/builder.rs
+++ b/crates/ragfs/src/core/builder.rs
@@ -6,7 +6,6 @@
//! `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;
@@ -14,11 +13,6 @@ 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::{
@@ -29,20 +23,10 @@ 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.
@@ -57,30 +41,16 @@ pub struct EncryptionConfig {
pub struct RagfsStack {
/// Mount manager (mount/unmount/list/stats/register_plugin live here).
pub mountable: Arc<MountableFS>,
- /// Data entry point: `Stats(PathLock(Mountable))`.
+ /// Data entry point: `Stats(Mountable)` — encryption is per-backend inside mount.
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.
@@ -90,28 +60,11 @@ pub async fn build_stack_with_mountable(
.await;
}
- 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(),
+ // 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>
));
- // 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 }
+ RagfsStack { mountable, top }
}
/// The single built-in plugin registration sequence (eliminates drift across call sites).
@@ -129,7 +82,7 @@ pub async fn register_builtin_plugins(fs: &MountableFS) {
#[cfg(test)]
mod tests {
use super::*;
- use crate::core::context::{FsContextInner, PathLockContext, FS_CTX};
+ use crate::core::context::{FsContextInner, FS_CTX};
use crate::core::{ConfigValue, PluginConfig, Result, WriteFlag};
use crate::crypto;
use std::collections::HashMap;
@@ -142,20 +95,6 @@ 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,
- },
}
}
@@ -210,107 +149,6 @@ 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 3587a13e3..3f1f36339 100644
--- a/crates/ragfs/src/core/context.rs
+++ b/crates/ragfs/src/core/context.rs
@@ -10,8 +10,7 @@
use std::sync::Arc;
-/// Immutable filesystem context snapshot. Currently carries `account_id` (the tenant)
-/// and optional `PathLockContext`.
+/// Immutable filesystem context snapshot. Currently carries only `account_id` (the tenant).
pub type FsContext = Arc<FsContextInner>;
tokio::task_local! {
@@ -19,20 +18,10 @@ 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 {
@@ -40,18 +29,6 @@ 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),
}
}
@@ -59,21 +36,6 @@ 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.
@@ -100,23 +62,6 @@ 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 542e4dec9..163fb88a3 100644
--- a/crates/ragfs/src/core/encryption_wrapper.rs
+++ b/crates/ragfs/src/core/encryption_wrapper.rs
@@ -17,10 +17,6 @@ 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;
@@ -44,10 +40,6 @@ 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 {
@@ -56,37 +48,17 @@ impl EncryptionWrappedFS {
&self.inner
}
- /// 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 {
+ /// 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 {
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) {
@@ -134,14 +106,6 @@ 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.
@@ -235,47 +199,6 @@ 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.
@@ -358,8 +281,6 @@ 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
@@ -370,73 +291,39 @@ impl FileSystem for EncryptionWrappedFS {
if !temp_root_ready {
self.create_temp_root(&temp_root).await?;
}
-
- // 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])
+ let written = match 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}"))
- })?,
- )
+ {
+ Ok(written) => written,
+ Err(Error::NotFound(_)) => {
+ self.create_temp_root(&temp_root).await?;
+ self.inner
+ .write(&temp_path, &envelope, 0, WriteFlag::Create)
+ .await?
}
- 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}"))
- })?,
- ),
- };
-
- // 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(()),
+ 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),
};
- 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}"
- ))),
+ 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)
}
async fn grep(
@@ -592,9 +479,6 @@ 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.
@@ -615,18 +499,6 @@ 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))
}
@@ -634,14 +506,7 @@ mod tests {
#[tokio::test]
async fn write_then_read_roundtrip_under_ctx() {
let inner = memfs_stack().await;
- let manager = memfs_pathlock_manager(inner.clone()).await;
- let enc = EncryptionWrappedFS::new(
- inner,
- [9u8; 32],
- crypto::PROVIDER_LOCAL,
- manager,
- "/mem".to_string(),
- );
+ let enc = EncryptionWrappedFS::new(inner, [9u8; 32], crypto::PROVIDER_LOCAL);
FS_CTX
.scope(ctx("tenant-1"), async {
@@ -657,14 +522,7 @@ mod tests {
#[tokio::test]
async fn on_disk_bytes_are_ciphertext_with_envelope() {
let inner = memfs_stack().await;
- let manager = memfs_pathlock_manager(inner.clone()).await;
- let enc = EncryptionWrappedFS::new(
- inner.clone(),
- [9u8; 32],
- crypto::PROVIDER_LOCAL,
- manager,
- "/mem".to_string(),
- );
+ let enc = EncryptionWrappedFS::new(inner.clone(), [9u8; 32], crypto::PROVIDER_LOCAL);
FS_CTX
.scope(ctx("tenant-1"), async {
@@ -683,14 +541,7 @@ mod tests {
#[tokio::test]
async fn read_without_account_id_errors() {
let inner = memfs_stack().await;
- let manager = memfs_pathlock_manager(inner.clone()).await;
- let enc = EncryptionWrappedFS::new(
- inner.clone(),
- [9u8; 32],
- crypto::PROVIDER_LOCAL,
- manager,
- "/mem".to_string(),
- );
+ let enc = EncryptionWrappedFS::new(inner.clone(), [9u8; 32], crypto::PROVIDER_LOCAL);
// Seed an envelope first.
FS_CTX
.scope(ctx("tenant-1"), async {
@@ -707,14 +558,7 @@ mod tests {
#[tokio::test]
async fn read_offset_size_slicing() {
let inner = memfs_stack().await;
- let manager = memfs_pathlock_manager(inner.clone()).await;
- let enc = EncryptionWrappedFS::new(
- inner,
- [1u8; 32],
- crypto::PROVIDER_LOCAL,
- manager,
- "/mem".to_string(),
- );
+ let enc = EncryptionWrappedFS::new(inner, [1u8; 32], crypto::PROVIDER_LOCAL);
FS_CTX
.scope(ctx("t"), async {
enc.write("/mem/a.txt", b"0123456789", 0, WriteFlag::Create)
@@ -730,14 +574,7 @@ mod tests {
#[tokio::test]
async fn grep_matches_encrypted_files() {
let inner = memfs_stack().await;
- let manager = memfs_pathlock_manager(inner.clone()).await;
- let enc = EncryptionWrappedFS::new(
- inner,
- [2u8; 32],
- crypto::PROVIDER_LOCAL,
- manager,
- "/mem".to_string(),
- );
+ let enc = EncryptionWrappedFS::new(inner, [2u8; 32], crypto::PROVIDER_LOCAL);
FS_CTX
.scope(ctx("t"), async {
enc.write(
@@ -761,14 +598,7 @@ mod tests {
#[tokio::test]
async fn write_rejects_nonzero_offset() {
let inner = memfs_stack().await;
- let manager = memfs_pathlock_manager(inner.clone()).await;
- let enc = EncryptionWrappedFS::new(
- inner,
- [2u8; 32],
- crypto::PROVIDER_LOCAL,
- manager,
- "/mem".to_string(),
- );
+ let enc = EncryptionWrappedFS::new(inner, [2u8; 32], crypto::PROVIDER_LOCAL);
FS_CTX
.scope(ctx("t"), async {
let r = enc.write("/mem/a.txt", b"x", 5, WriteFlag::Create).await;
@@ -780,14 +610,7 @@ mod tests {
#[tokio::test]
async fn create_writes_encrypted_empty_file() {
let inner = memfs_stack().await;
- let manager = memfs_pathlock_manager(inner.clone()).await;
- let enc = EncryptionWrappedFS::new(
- inner.clone(),
- [2u8; 32],
- crypto::PROVIDER_LOCAL,
- manager,
- "/mem".to_string(),
- );
+ let enc = EncryptionWrappedFS::new(inner.clone(), [2u8; 32], crypto::PROVIDER_LOCAL);
FS_CTX
.scope(ctx("t"), async {
enc.create("/mem/empty.txt").await.unwrap();
@@ -803,14 +626,7 @@ mod tests {
#[tokio::test]
async fn cross_account_cannot_decrypt() {
let inner = memfs_stack().await;
- let manager = memfs_pathlock_manager(inner.clone()).await;
- let enc = EncryptionWrappedFS::new(
- inner,
- [3u8; 32],
- crypto::PROVIDER_LOCAL,
- manager,
- "/mem".to_string(),
- );
+ let enc = EncryptionWrappedFS::new(inner, [3u8; 32], crypto::PROVIDER_LOCAL);
FS_CTX
.scope(ctx("acct-A"), async {
enc.write("/mem/a.txt", b"owned by A", 0, WriteFlag::Create)
@@ -828,14 +644,7 @@ mod tests {
#[tokio::test]
async fn write_rejects_append_flag() {
let inner = memfs_stack().await;
- let manager = memfs_pathlock_manager(inner.clone()).await;
- let enc = EncryptionWrappedFS::new(
- inner,
- [4u8; 32],
- crypto::PROVIDER_LOCAL,
- manager,
- "/mem".to_string(),
- );
+ let enc = EncryptionWrappedFS::new(inner, [4u8; 32], crypto::PROVIDER_LOCAL);
FS_CTX
.scope(ctx("t"), async {
enc.write("/mem/a.txt", b"first", 0, WriteFlag::Create)
@@ -852,14 +661,7 @@ mod tests {
#[tokio::test]
async fn write_rejects_non_replacing_none_flag() {
let inner = memfs_stack().await;
- let manager = memfs_pathlock_manager(inner.clone()).await;
- let enc = EncryptionWrappedFS::new(
- inner,
- [4u8; 32],
- crypto::PROVIDER_LOCAL,
- manager,
- "/mem".to_string(),
- );
+ let enc = EncryptionWrappedFS::new(inner, [4u8; 32], crypto::PROVIDER_LOCAL);
FS_CTX
.scope(ctx("t"), async {
enc.write("/mem/a.txt", b"first", 0, WriteFlag::Create)
@@ -874,14 +676,7 @@ mod tests {
#[tokio::test]
async fn rename_rejects_cross_account_paths() {
let inner = memfs_stack_at("/local").await;
- let manager = memfs_pathlock_manager(inner.clone()).await;
- let enc = EncryptionWrappedFS::new(
- inner,
- [5u8; 32],
- crypto::PROVIDER_LOCAL,
- manager,
- "/local".to_string(),
- );
+ let enc = EncryptionWrappedFS::new(inner, [5u8; 32], crypto::PROVIDER_LOCAL);
let result = FS_CTX
.scope(ctx("acct-a"), async {
enc.mkdir("/local/acct-a", 0).await.unwrap();
@@ -899,14 +694,7 @@ mod tests {
#[tokio::test]
async fn write_replaces_stale_internal_temp_file_before_publish() {
let inner = memfs_stack().await;
- let manager = memfs_pathlock_manager(inner.clone()).await;
- let enc = EncryptionWrappedFS::new(
- inner.clone(),
- [6u8; 32],
- crypto::PROVIDER_LOCAL,
- manager,
- "/mem".to_string(),
- );
+ let enc = EncryptionWrappedFS::new(inner.clone(), [6u8; 32], crypto::PROVIDER_LOCAL);
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 7a9c7965e..e76044bf8 100644
--- a/crates/ragfs/src/core/filesystem.rs
+++ b/crates/ragfs/src/core/filesystem.rs
@@ -197,52 +197,6 @@ 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
@@ -256,17 +210,6 @@ 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
@@ -1073,7 +1016,7 @@ mod tests {
let entries = root_tree(&fs, false, None, Some(1)).await;
assert_eq!(entries.len(), 2);
- assert_tree_names(&entries, &["sub", "a.txt"]);
+ assert_tree_names(&entries, &["a.txt", "sub"]);
}
#[tokio::test]
@@ -1138,8 +1081,8 @@ mod tests {
let entries = fs.tree_directory("/", false, None, None).await.unwrap();
assert_eq!(entries.len(), 2);
- assert_eq!(entries[0].path, "/sub");
- assert_eq!(entries[0].rel_path, "sub");
+ assert_eq!(entries[0].path, "/a.txt");
+ assert_eq!(entries[0].rel_path, "a.txt");
}
#[tokio::test]
diff --git a/crates/ragfs/src/core/internal_names.rs b/crates/ragfs/src/core/internal_names.rs
deleted file mode 100644
index 7d703cd22..000000000
--- a/crates/ragfs/src/core/internal_names.rs
+++ /dev/null
@@ -1,27 +0,0 @@
-//! 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 d2d72a989..6bc43e939 100644
--- a/crates/ragfs/src/core/mod.rs
+++ b/crates/ragfs/src/core/mod.rs
@@ -13,7 +13,6 @@ 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;
@@ -24,10 +23,10 @@ pub mod types;
// Re-export commonly used types
pub use crate::multibackend::{FsContextResolver, MetaStateStore};
pub use builder::{
- build_default_stack, build_stack_with_mountable, register_builtin_plugins,
- EncryptionConfig as BuilderEncryptionConfig, RagfsConfig, RagfsStack,
+ build_default_stack, register_builtin_plugins, EncryptionConfig as BuilderEncryptionConfig,
+ RagfsConfig, RagfsStack,
};
-pub use context::{FsContext, FsContextInner, FsContextView, PathLockContext, FS_CTX};
+pub use context::{FsContext, FsContextInner, FsContextView, 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 ed1c66d1d..9767214d2 100644
--- a/crates/ragfs/src/core/mountable.rs
+++ b/crates/ragfs/src/core/mountable.rs
@@ -8,19 +8,16 @@ use async_trait::async_trait;
use radix_trie::{Trie, TrieCommon};
use serde_json::Value;
use std::collections::HashMap;
-use std::sync::{Arc, OnceLock};
-use std::time::Duration;
+use std::sync::Arc;
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;
-use super::internal_names::is_hidden_internal_name;
+/// Python-side transaction path-lock marker — hidden in all listing/grep operations.
+const PATH_LOCK_FILE: &str = ".path.ovlock";
use super::encryption_wrapper::EncryptionWrappedFS;
use super::errors::{Error, Result};
@@ -77,9 +74,6 @@ 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>,
@@ -149,21 +143,6 @@ 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;
@@ -186,14 +165,6 @@ 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?;
@@ -217,7 +188,6 @@ 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,
}
@@ -238,7 +208,6 @@ 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,
@@ -257,13 +226,6 @@ 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;
@@ -361,18 +323,7 @@ impl MountableFS {
config.name
)));
}
- 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(),
- ))
+ Arc::new(EncryptionWrappedFS::new(storage_fs, rk, pt))
}
_ => storage_fs,
}
@@ -445,11 +396,6 @@ 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,
@@ -457,8 +403,6 @@ impl MountableFS {
MultiBackendBuildContext {
enc_root_key,
enc_provider_type,
- pathlock_manager,
- backend_prefix: config.mount_path.clone(),
},
)
.await
@@ -595,66 +539,20 @@ impl MountableFS {
return Ok(true);
}
- 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);
+ if let Some(multiwrite) = Self::as_multiwrite(&src_mount.fs) {
+ return multiwrite
+ .copy_within_primary(&src_rel_path, &dst_rel_path)
+ .await;
}
- 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}")));
- }
- };
-
- 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 Some(raw_backend) = src_mount.raw_fs.clone() else {
+ return Ok(false);
};
- 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}"
- ))),
- }
+ 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)
}
/// Copy one file within one raw backend in bounded-size chunks.
@@ -864,83 +762,10 @@ 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_internal_dir(&rel_path).await?;
+ let mut entries = mount_info.fs.read_dir(&rel_path).await?;
+ entries.retain(|e| e.name != PATH_LOCK_FILE);
sort_directory_entries(&mut entries);
Ok(entries)
}
@@ -1036,12 +861,12 @@ impl FileSystem for MountableFS {
)
.await?;
- // Filter out internal files from public search results.
+ // Filter out path-lock markers.
result.matches.retain(|m| {
m.file
.rsplit('/')
.next()
- .map_or(true, |name| !is_hidden_internal_name(name))
+ .map_or(true, |name| name != PATH_LOCK_FILE)
});
result.count = result.matches.len();
Ok(result)
@@ -1077,12 +902,12 @@ impl FileSystem for MountableFS {
}
}
- // Filter out internal files from public tree results.
+ // Filter out path-lock markers.
entries.retain(|e| {
e.path
.rsplit('/')
.next()
- .map_or(true, |name| !is_hidden_internal_name(name))
+ .map_or(true, |name| name != PATH_LOCK_FILE)
});
Ok(entries)
@@ -1132,7 +957,7 @@ impl FileSystem for MountableFS {
.path
.rsplit('/')
.next()
- .map_or(true, |name| !is_hidden_internal_name(name))
+ .map_or(true, |name| name != PATH_LOCK_FILE)
});
Ok(page)
@@ -1438,32 +1263,6 @@ 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();
@@ -1474,22 +1273,6 @@ 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");
@@ -1501,7 +1284,7 @@ mod tests {
#[tokio::test]
async fn test_mountable_fs_creation() {
- let mfs = Arc::new(MountableFS::new());
+ let mfs = MountableFS::new();
let mounts = mfs.list_mounts().await;
assert!(mounts.is_empty());
}
@@ -1610,55 +1393,6 @@ 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() {
@@ -1715,27 +1449,16 @@ 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 cache_provider = Arc::new(MemoryCacheProvider::new());
- let mfs = Arc::new(MountableFS::with_cache(
- cache_provider.clone(),
+ let provider = Arc::new(MemoryCacheProvider::new());
+ let mfs = MountableFS::with_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();
@@ -1773,13 +1496,13 @@ mod tests {
"missing account context must not receive cached plaintext"
);
- let file_key = cache_provider
+ let file_key = provider
.keys()
.await
.into_iter()
.find(|key| key.contains(":file:"))
.expect("encrypted read should populate one file cache object");
- let encoded = cache_provider
+ let encoded = provider
.get(&file_key)
.await
.unwrap()
@@ -1801,27 +1524,17 @@ 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 = Arc::new(MountableFS::with_cache(
+ let mfs = MountableFS::with_cache(
Arc::new(MemoryCacheProvider::new()),
CacheNamespace::new("encrypted-multiwrite-test"),
CachePolicy::default(),
- ));
- mfs.register_plugin(MemFSPlugin).await;
+ );
+ mfs.register_plugin(MockPlugin::new("primary")).await;
+ mfs.register_plugin(MockPlugin::new("backupfs")).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("memfs", "memfs", "/local");
+ let mut config = multiwrite_test_config("primary", "backupfs", "/local");
config.server_encryption_enabled = true;
config.primary_encryption_enabled = true;
mfs.mount(config).await.unwrap();
@@ -1890,7 +1603,7 @@ mod tests {
#[tokio::test]
async fn test_mount_duplicate_error() {
- let mfs = Arc::new(MountableFS::new());
+ let mfs = MountableFS::new();
mfs.register_plugin(MockPlugin::new("mock")).await;
let config = test_config("mock", "/mock");
@@ -2144,7 +1857,7 @@ mod tests {
#[tokio::test]
async fn test_build_multi_write_fs_rejects_primary_encryption_disable() {
- let mfs = with_test_pathlock_manager(Arc::new(MountableFS::new())).await;
+ let mfs = MountableFS::new();
mfs.register_plugin(MockPlugin::new("primary")).await;
mfs.register_plugin(MockPlugin::new("backupfs")).await;
mfs.set_encryption_config(Some([7u8; 32]), Some(1)).await;
@@ -2183,66 +1896,9 @@ 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 = with_test_pathlock_manager(Arc::new(MountableFS::new())).await;
+ let mfs = MountableFS::new();
mfs.register_plugin(MockPlugin::new("primary")).await;
mfs.register_plugin(MockPlugin::new("backupfs")).await;
@@ -2284,7 +1940,7 @@ mod tests {
#[tokio::test]
async fn test_build_multi_write_fs_rejects_reserved_primary_backup_name() {
- let mfs = with_test_pathlock_manager(Arc::new(MountableFS::new())).await;
+ let mfs = MountableFS::new();
mfs.register_plugin(MockPlugin::new("primary")).await;
mfs.register_plugin(MockPlugin::new("backupfs")).await;
@@ -2323,23 +1979,11 @@ mod tests {
#[tokio::test]
async fn test_single_backend_mount_wraps_stats_outside_encryption() {
- use crate::lock::{
- MemoryPathLockProvider, PathLockConfig, PathLockManager, PathLockProvider,
- };
- use crate::plugins::MemFSPlugin;
-
- let mfs = Arc::new(MountableFS::new());
- mfs.register_plugin(MemFSPlugin).await;
+ let mfs = MountableFS::new();
+ mfs.register_plugin(MockPlugin::new("mock")).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("memfs", "/mock")).await.unwrap();
+ mfs.mount(test_config("mock", "/mock")).await.unwrap();
let mounts = mfs.mounts.read().await;
let mount_info = mounts.get("/mock").expect("mounted entry should exist");
@@ -2356,7 +2000,7 @@ mod tests {
#[tokio::test]
async fn test_multiwrite_mount_wraps_stats_outside_multiwrite() {
- let mfs = with_test_pathlock_manager(Arc::new(MountableFS::new())).await;
+ let mfs = MountableFS::new();
mfs.register_plugin(MockPlugin::new("primary")).await;
mfs.register_plugin(MockPlugin::new("backupfs")).await;
@@ -2379,7 +2023,7 @@ mod tests {
#[tokio::test]
async fn test_multiwrite_raw_access_is_rejected() {
- let mfs = with_test_pathlock_manager(Arc::new(MountableFS::new())).await;
+ let mfs = MountableFS::new();
mfs.register_plugin(MockPlugin::new("primary")).await;
mfs.register_plugin(MockPlugin::new("backupfs")).await;
@@ -2399,7 +2043,7 @@ mod tests {
#[tokio::test]
async fn test_mountable_multiwrite_admin_smoke() {
- let mfs = with_test_pathlock_manager(Arc::new(MountableFS::new())).await;
+ let mfs = MountableFS::new();
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 db2f7e1ef..0d204dba1 100644
--- a/crates/ragfs/src/core/multibackend_wrapper.rs
+++ b/crates/ragfs/src/core/multibackend_wrapper.rs
@@ -19,7 +19,6 @@ 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::{
@@ -30,7 +29,6 @@ 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,
@@ -583,17 +581,6 @@ 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 {
@@ -1303,9 +1290,6 @@ 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
})
@@ -1323,9 +1307,6 @@ 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
})
@@ -1333,9 +1314,6 @@ 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
})
@@ -1343,9 +1321,6 @@ 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;
}
@@ -1353,14 +1328,6 @@ 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();
@@ -1416,9 +1383,6 @@ 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;
}
@@ -1426,11 +1390,6 @@ 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();
@@ -1472,9 +1431,6 @@ 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,
@@ -1485,9 +1441,6 @@ 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 35d9f64f5..767091b0b 100644
--- a/crates/ragfs/src/core/types.rs
+++ b/crates/ragfs/src/core/types.rs
@@ -187,16 +187,9 @@ impl FileInfo {
/// Write operation flags
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
pub enum WriteFlag {
- /// 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 new file or truncate existing
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 cd2a77c73..fc2a287a6 100644
--- a/crates/ragfs/src/git/enumerate.rs
+++ b/crates/ragfs/src/git/enumerate.rs
@@ -14,8 +14,6 @@
//! 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;
@@ -49,12 +47,11 @@ pub fn prune_path(rel: &str) -> bool {
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 2: any segment equals or starts with ".path.ovlock"
+ for seg in &segments {
+ if seg.starts_with(".path.ovlock") {
+ return true;
+ }
}
// Rule 3a: any intermediate segment named exactly "embedding_cache"
@@ -392,9 +389,6 @@ 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 3b583f745..c83488fec 100644
--- a/crates/ragfs/src/git/service.rs
+++ b/crates/ragfs/src/git/service.rs
@@ -1303,8 +1303,6 @@ 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 06fad00b8..082e9b4e1 100644
--- a/crates/ragfs/src/lib.rs
+++ b/crates/ragfs/src/lib.rs
@@ -33,7 +33,6 @@
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
deleted file mode 100644
index 45d7c5bdf..000000000
--- a/crates/ragfs/src/lock/codec.rs
+++ /dev/null
@@ -1,103 +0,0 @@
-//! 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
deleted file mode 100644
index cbf1e79de..000000000
--- a/crates/ragfs/src/lock/manager.rs
+++ /dev/null
@@ -1,1844 +0,0 @@
-//! 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 entries: Vec<(String, String, Vec<String>)> = {
- let reg = refresh_registry.read().await;
- reg.entries
- .iter()
- .map(|(lease_ref, entry)| {
- (
- lease_ref.clone(),
- entry.lease.owner_id.clone(),
- entry.lease.lock_paths.clone(),
- )
- })
- .collect()
- };
- for (lease_ref, owner_id, lock_paths) in entries {
- 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,
- }
- }
- 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,
- }
- }
-
- /// 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 } = &err {
- metrics.record_conflict(PathLockConflict {
- lock_path: lock_path.clone(),
- conflicting_owner: owner.clone(),
- conflicting_kind: PathLockKind::Tree, // ponytail: approximate — exact resolution would require reading the token
- });
- }
- }
-
- // 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,
- } = &err
- {
- metrics.record_conflict(PathLockConflict {
- lock_path: lock_path.clone(),
- conflicting_owner: owner.clone(),
- conflicting_kind: PathLockKind::Tree,
- });
- }
- }
-
- 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(),
- });
- }
- 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,
- });
- }
- // 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,
- });
- }
- }
- }
- 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,
- });
- }
- }
-
- 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,
- });
- }
- }
- }
- 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 {
- if let Err(error) = self
- .provider
- .remove_token(&lock_path, &entry.lease.owner_id)
- .await
- {
- 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 {
- if let Err(error) = self.provider.remove_token(&lock_path, &owner_id).await {
- 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,
- });
- }
- 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::core::{FsContextInner, PathLockContext, FS_CTX};
- 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,
- }
-
- 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),
- }
- }
- }
-
- #[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.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
deleted file mode 100644
index 9a60bff9c..000000000
--- a/crates/ragfs/src/lock/metrics.rs
+++ /dev/null
@@ -1,42 +0,0 @@
-//! 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
deleted file mode 100644
index e50e3c9cc..000000000
--- a/crates/ragfs/src/lock/mod.rs
+++ /dev/null
@@ -1,32 +0,0 @@
-//! 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
deleted file mode 100644
index 86025fb80..000000000
--- a/crates/ragfs/src/lock/provider.rs
+++ /dev/null
@@ -1,336 +0,0 @@
-//! 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(),
- });
- }
- 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,
- }),
- 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
deleted file mode 100644
index 2f32da81e..000000000
--- a/crates/ragfs/src/lock/resolver.rs
+++ /dev/null
@@ -1,203 +0,0 @@
-//! 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
deleted file mode 100644
index b16c42b21..000000000
--- a/crates/ragfs/src/lock/types.rs
+++ /dev/null
@@ -1,198 +0,0 @@
-//! 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,
- },
-
- /// 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
deleted file mode 100644
index 4e690884b..000000000
--- a/crates/ragfs/src/lock/wrapper.rs
+++ /dev/null
@@ -1,368 +0,0 @@
-//! 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 0f657d850..0ac98d581 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::RelativePathFsContextResolver;
+use crate::multibackend::meta::MountRootFsContextResolver;
use crate::multibackend::types::MultiBackendBuildContext;
use crate::shape::validate::ensure_backend_shape;
@@ -85,8 +85,6 @@ 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()
@@ -148,8 +146,6 @@ 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
@@ -180,6 +176,8 @@ 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(RelativePathFsContextResolver))
+ .ctx_resolver(Arc::new(MountRootFsContextResolver::new(
+ &config.mount_path,
+ )))
.build()
}
diff --git a/crates/ragfs/src/multibackend/meta.rs b/crates/ragfs/src/multibackend/meta.rs
index 97110884f..d63766170 100644
--- a/crates/ragfs/src/multibackend/meta.rs
+++ b/crates/ragfs/src/multibackend/meta.rs
@@ -45,13 +45,44 @@ impl FsContextResolver for DefaultFsContextResolver {
}
}
-/// Resolver that extracts `account_id` from mount-relative paths such as `/{account_id}/...`.
-pub struct RelativePathFsContextResolver;
+/// 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,
+ }
+ }
+}
-impl FsContextResolver for RelativePathFsContextResolver {
+impl FsContextResolver for MountRootFsContextResolver {
fn resolve(&self, path: &str) -> Result<FsContext> {
- let normalized = path.trim_start_matches('/');
- let account_id = normalized.split('/').next().unwrap_or_default();
+ 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();
if account_id.is_empty() {
return Err(Error::internal(format!(
"cannot resolve FsContext from path: {path}"
@@ -144,12 +175,12 @@ impl MetaStateStore {
Arc::new(FsContextInner::new("_system".to_string()))
}
- /// Build the effective context for metadata access.
+ /// - root directory using `_system` context
fn effective_meta_ctx(dir: &str, ctx: &FsContext) -> FsContext {
if dir == "/" {
- Arc::new(Self::system_ctx().with_auto_pathlock_disabled())
+ Self::system_ctx()
} else {
- Arc::new(ctx.with_auto_pathlock_disabled())
+ ctx.clone()
}
}
@@ -501,7 +532,6 @@ pub fn current_required_ctx() -> Result<FsContext> {
#[cfg(test)]
mod tests {
use super::*;
- use crate::core::context::PathLockContext;
use crate::plugins::memfs::MemFileSystem;
use std::sync::Arc;
@@ -533,6 +563,15 @@ 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 78bb71d66..8e097ee4f 100644
--- a/crates/ragfs/src/multibackend/types.rs
+++ b/crates/ragfs/src/multibackend/types.rs
@@ -1,20 +1,12 @@
//! 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)]
+#[derive(Clone, Copy)]
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 85be8ed6e..e2b1775b0 100644
--- a/crates/ragfs/src/plugins/kvfs/mod.rs
+++ b/crates/ragfs/src/plugins/kvfs/mod.rs
@@ -193,9 +193,6 @@ 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);
}
@@ -214,7 +211,7 @@ impl FileSystem for KVFileSystem {
Ok(data.len() as u64)
}
None => {
- if matches!(flags, WriteFlag::Create | WriteFlag::CreateNew) {
+ if matches!(flags, WriteFlag::Create) {
store.insert(key, KVEntry::new(data.to_vec()));
Ok(data.len() as u64)
} else {
@@ -224,38 +221,6 @@ 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 a7619467d..af1e97740 100644
--- a/crates/ragfs/src/plugins/localfs/mod.rs
+++ b/crates/ragfs/src/plugins/localfs/mod.rs
@@ -93,138 +93,6 @@ 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 = fd_lock::RwLock::new(file);
- let mut file = lock
- .write()
- .map_err(|e| Error::plugin(format!("failed to lock for compare_and_write: {}", e)))?;
- 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 = fd_lock::RwLock::new(file);
- let mut file = lock
- .write()
- .map_err(|e| Error::plugin(format!("failed to lock for compare_and_remove: {}", e)))?;
- 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
@@ -946,9 +814,6 @@ 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);
}
@@ -977,29 +842,6 @@ 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 bdec5a9e8..af85f9c19 100644
--- a/crates/ragfs/src/plugins/memfs/mod.rs
+++ b/crates/ragfs/src/plugins/memfs/mod.rs
@@ -280,9 +280,6 @@ 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);
}
@@ -302,8 +299,8 @@ impl FileSystem for MemFileSystem {
Ok(data.len() as u64)
}
None => {
- // Create file if Create or CreateNew flag is set
- if matches!(flags, WriteFlag::Create | WriteFlag::CreateNew) {
+ // Create file if Create flag is set
+ if matches!(flags, WriteFlag::Create) {
// Check parent exists
if let Some(parent) = Self::parent_path(&normalized) {
match entries.get(&parent) {
@@ -324,39 +321,6 @@ 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 e37b8161e..dddda4593 100644
--- a/crates/ragfs/src/plugins/s3fs/client.rs
+++ b/crates/ragfs/src/plugins/s3fs/client.rs
@@ -110,30 +110,6 @@ 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,
@@ -510,46 +486,6 @@ 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 {
@@ -616,72 +552,6 @@ 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
@@ -701,36 +571,6 @@ 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 d49334965..38e378094 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;
+use crate::core::glob::{PreparedGlob, validate_pattern};
use crate::core::{
ConfigParameter, Error, FileInfo, FileSystem, GlobEntry, GlobPage, GrepMatch, GrepResult,
PluginConfig, Result, ServicePlugin, TreeEntry, WriteFlag,
@@ -573,19 +573,12 @@ 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);
- 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?;
- }
- }
+ // S3 always replaces the full object
+ self.client.put_object(&key, data.to_vec()).await?;
// Invalidate caches
self.dir_cache.invalidate_parent(&normalized).await;
@@ -594,48 +587,6 @@ 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 f16314bed..5fa01efb7 100644
--- a/crates/ragfs/src/plugins/sqlfs/backend.rs
+++ b/crates/ragfs/src/plugins/sqlfs/backend.rs
@@ -46,12 +46,6 @@ 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>>;
@@ -284,35 +278,6 @@ 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 0ab7bb367..f990850c8 100644
--- a/crates/ragfs/src/plugins/sqlfs/mod.rs
+++ b/crates/ragfs/src/plugins/sqlfs/mod.rs
@@ -110,27 +110,6 @@ 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 {
@@ -282,11 +261,9 @@ impl FileSystem for SQLFileSystem {
async fn read(&self, path: &str, offset: u64, size: u64) -> Result<Vec<u8>> {
let normalized = Self::normalize_path(path);
- let normalized_for_db = normalized.clone();
- match self
- .run_blocking_db(move |backend| backend.read_file(&normalized_for_db))
- .await?
- {
+ let backend = self.backend.read().await;
+
+ match backend.read_file(&normalized)? {
Some((is_dir, data)) => {
if is_dir {
return Err(Error::IsADirectory(normalized));
@@ -331,85 +308,39 @@ impl FileSystem for SQLFileSystem {
));
}
- 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 backend = self.backend.read().await;
- if matches!(flags, WriteFlag::CreateNew) {
- return Err(Error::AlreadyExists(normalized_for_db.clone()));
- }
+ let exists = backend.path_exists(&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));
- }
+ if exists {
+ // Check if it's a directory
+ if backend.is_directory(&normalized)? {
+ return Err(Error::IsADirectory(normalized));
+ }
- let parent = backend.parent_path(&normalized_for_db);
- if parent != "/" && !backend.is_directory(&parent)? {
- return Err(Error::not_found(&parent));
- }
+ // Update existing file
+ backend.update_file(&normalized, data)?;
+ } else {
+ // Create new file
+ if !matches!(flags, WriteFlag::Create) {
+ return Err(Error::not_found(&normalized));
+ }
- backend.create_file(&normalized_for_db, 0o644, &data_owned)?;
- Ok(true)
+ // Check parent exists
+ let parent = backend.parent_path(&normalized);
+ if parent != "/" {
+ if !backend.is_directory(&parent)? {
+ return Err(Error::not_found(&parent));
}
- })
- .await?;
-
- if created_new {
- self.cache.invalidate_parent(&normalized).await;
- }
+ }
- Ok(data.len() as u64)
- }
+ backend.create_file(&normalized, 0o644, data)?;
- 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 {
+ // Invalidate parent cache
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)
+ Ok(data.len() as u64)
}
async fn read_dir(&self, path: &str) -> Result<Vec<FileInfo>> {
@@ -420,21 +351,19 @@ impl FileSystem for SQLFileSystem {
return Ok(files);
}
- 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));
- }
+ let backend = self.backend.read().await;
- if !backend.is_directory(&normalized_for_db)? {
- return Err(Error::NotADirectory(normalized_for_db));
- }
+ // Check if directory exists
+ if !backend.path_exists(&normalized)? {
+ return Err(Error::not_found(&normalized));
+ }
- backend.list_directory(&list_path)
- })
- .await?;
+ if !backend.is_directory(&normalized)? {
+ return Err(Error::NotADirectory(normalized));
+ }
+
+ // List directory
+ let entries = backend.list_directory(&normalized)?;
// Convert to FileInfo
let mut files = Vec::new();
@@ -458,11 +387,9 @@ impl FileSystem for SQLFileSystem {
async fn stat(&self, path: &str) -> Result<FileInfo> {
let normalized = Self::normalize_path(path);
- let normalized_for_db = normalized.clone();
- match self
- .run_blocking_db(move |backend| backend.get_metadata(&normalized_for_db))
- .await?
- {
+ let backend = self.backend.read().await;
+
+ match backend.get_metadata(&normalized)? {
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 254c78e40..4a098b39e 100644
--- a/crates/ragfs/src/shape/probe.rs
+++ b/crates/ragfs/src/shape/probe.rs
@@ -2,7 +2,6 @@ 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};
@@ -10,6 +9,8 @@ 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();
@@ -35,7 +36,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("");
- is_hidden_runtime_lock_name(name)
+ name == PATH_LOCK_FILE || name.starts_with(EXACT_LOCK_FILE_PREFIX)
}
/// Read the raw guard-file bytes from the backend root.
diff --git a/openviking/async_client.py b/openviking/async_client.py
index 52904f626..19b75be32 100644
--- a/openviking/async_client.py
+++ b/openviking/async_client.py
@@ -109,6 +109,11 @@ 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 68613729e..86544ac87 100644
--- a/openviking/metrics/datasources/observer_state.py
+++ b/openviking/metrics/datasources/observer_state.py
@@ -3,10 +3,11 @@
from __future__ import annotations
+import time
from typing import Any
from openviking.metrics.core.base import ReadEnvelope
-from openviking.storage.viking_fs import get_viking_fs
+from openviking.storage.transaction import get_lock_manager
from openviking_cli.utils import run_async
from .base import DomainStatsMetricDataSource, StateMetricDataSource
@@ -61,27 +62,36 @@ class ObserverStateDataSource(DomainStatsMetricDataSource):
class LockStateDataSource(StateMetricDataSource):
"""
- Read lock-manager counters from the pathlock observe snapshot.
+ Read lock-manager counters needed by lock-related state collectors.
- The datasource reads the ``pathlock_observe()`` snapshot to derive active,
- waiting, and stale lock counts.
+ The datasource inspects active lock handles and derives a stale-handle count using the
+ current in-process timeout heuristic.
"""
def read_lock_state(self) -> ReadEnvelope[tuple[int, int, int]]:
"""
- Read active, waiting, and stale lock counts from the pathlock observe snapshot.
+ Read active and stale lock counts from the global transaction lock manager.
Returns:
- A tuple of ``(active_locks, waiting_locks, stale_locks_removed)``.
+ A tuple of `(active_locks, waiting_locks, stale_handles)` where waiting locks are
+ currently not tracked separately and therefore remain `0`.
"""
def _read() -> tuple[int, int, int]:
- 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
+ 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
return self.safe_read(_read, default=(0, 0, 0))
diff --git a/openviking/parse/image_rewrite.py b/openviking/parse/image_rewrite.py
index 8f2482cb9..66e8e0878 100644
--- a/openviking/parse/image_rewrite.py
+++ b/openviking/parse/image_rewrite.py
@@ -11,12 +11,15 @@ images themselves are stored next to the markdown file referencing them).
import json
import re
from pathlib import Path
-from typing import Any, Dict, Optional, Set
+from typing import TYPE_CHECKING, 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"!\[([^\]]*)\]\(((?:[^()]|\([^()]*\))+)\)")
@@ -256,7 +259,7 @@ async def _discover_mappings(
async def rewrite_image_uris(
root_uri: str,
ctx: Optional[RequestContext] = None,
- lease_ref: Optional[Dict[str, Any]] = None,
+ lock_handle: Optional["LockHandle"] = None,
) -> Dict[str, int]:
"""Rewrite local image references in markdown files to viking:// URIs.
@@ -274,7 +277,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
- lease_ref: Optional lease reference held by the caller. When the caller
+ lock_handle: Optional lock handle 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.
@@ -334,11 +337,12 @@ 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,
- lease_ref=lease_ref,
+ lock_handle=lock_handle,
)
files_processed += 1
references_rewritten += rewrite_count
@@ -350,9 +354,7 @@ 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,
- lease_ref=lease_ref,
+ f"{map_dir}/{IMAGE_MAPPINGS_FILENAME}", ctx=ctx, lock_handle=lock_handle
)
except Exception as e:
logger.warning(
diff --git a/openviking/pyagfs/async_client.py b/openviking/pyagfs/async_client.py
index 5182f2b71..3e1fd7457 100644
--- a/openviking/pyagfs/async_client.py
+++ b/openviking/pyagfs/async_client.py
@@ -253,238 +253,3 @@ 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 5a1910ee4..d19b1095e 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,9 +383,7 @@ 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:
@@ -637,34 +635,14 @@ class LegacyAPIKeyManager:
except AGFSNotFoundError:
return 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:
+ async def _write_json(self, path: str, data: dict) -> 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,
- fs_ctx=self._fs_ctx_with_lease(path, lease_ref),
- )
+ await self._async_agfs.write(path, content)
async def _ensure_parent_dirs_async(self, path: str) -> None:
"""Recursively create all parent directories for a file path."""
@@ -676,38 +654,37 @@ class LegacyAPIKeyManager:
async def _save_accounts_json(self) -> None:
"""Persist the global accounts list."""
try:
- lease = await self._async_agfs.pathlock_acquire_exact(ACCOUNTS_PATH, timeout_secs=10.0)
+ 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)
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:
- lease = await self._async_agfs.pathlock_acquire_exact(path, timeout_secs=10.0)
+ 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})
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 290394cc7..e79a6e10f 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.errors import LockAcquisitionError
+from openviking.storage.transaction import get_lock_manager
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_viking_fs()._async_agfs.pathlock_release(self.lock_handle)
+ await get_lock_manager().release(self.lock_handle)
self.lock_handle = None
if self.mode == "shared" and self.local_path:
@@ -142,12 +142,7 @@ 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,
- lease_ref=resolved.lock_handle,
- )
+ await self._write_shared_meta(shared_id, ctx, meta)
async def mark_consumed(self, resolved: ResolvedTempUpload, ctx: RequestContext) -> None:
shared_id = _parse_shared_temp_file_id(resolved.temp_file_id)
@@ -158,7 +153,7 @@ class TempUploadStore:
uri,
recursive=True,
ctx=self._internal_ctx(ctx),
- lease_ref=resolved.lock_handle,
+ lock_handle=resolved.lock_handle,
)
async def try_cleanup_invalid_or_expired(
@@ -320,9 +315,9 @@ class TempUploadStore:
_shared_upload_uri(self.temp_cfg, ctx, upload_id),
ctx=internal_ctx,
)
- try:
- lease = await vfs._async_agfs.pathlock_acquire_tree(lock_path, timeout_secs=0.0)
- except LockAcquisitionError:
+ handle = get_lock_manager().create_handle()
+ acquired = await get_lock_manager().acquire_tree(handle, lock_path, timeout=0.0)
+ if not acquired:
raise PermissionDeniedError("Temporary upload is being consumed.")
try:
@@ -333,7 +328,7 @@ class TempUploadStore:
meta["state"] = "consuming"
meta["updated_at"] = now
- await self._write_shared_meta(upload_id, ctx, meta, lease_ref=lease)
+ await self._write_shared_meta(upload_id, ctx, meta)
file_ext = meta.get("file_ext") or ".tmp"
fd, temp_path = tempfile.mkstemp(prefix="ov_shared_upload_", suffix=file_ext)
@@ -352,11 +347,11 @@ class TempUploadStore:
temp_file_id=temp_file_id,
original_filename=meta.get("original_filename") or None,
local_path=temp_path,
- lock_handle=lease,
+ lock_handle=handle,
)
except Exception:
with suppress(Exception):
- await vfs._async_agfs.pathlock_release(lease)
+ await get_lock_manager().release(handle)
raise
async def _read_shared_meta(self, upload_id: str, ctx: RequestContext) -> dict[str, Any]:
@@ -375,15 +370,12 @@ 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 908d5a858..4a93fc776 100644
--- a/openviking/server/user_config.py
+++ b/openviking/server/user_config.py
@@ -12,11 +12,13 @@ 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
@@ -38,20 +40,14 @@ async def _user_config_lock(
viking_fs: VikingFS,
uri: str,
ctx: RequestContext,
-) -> AsyncIterator[Optional[dict[str, Any]]]:
+) -> AsyncIterator[Optional[LockHandle]]:
uri_to_path = getattr(viking_fs, "_uri_to_path", None)
- 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):
+ if not callable(uri_to_path):
yield None
return
path = uri_to_path(uri, ctx=ctx)
- lease = await acquire(path)
- try:
- yield lease
- finally:
- await release(lease)
+ async with LockContext(get_lock_manager(), [path], lock_mode="exact") as handle:
+ yield handle
def _user_config_from_payload(payload: Any) -> UserConfig:
@@ -160,7 +156,7 @@ async def update_user_config(
sort_keys=True,
),
ctx=ctx,
- lease_ref=handle,
+ lock_handle=handle,
)
return result
@@ -181,7 +177,7 @@ async def write_user_config(
sort_keys=True,
),
ctx=ctx,
- lease_ref=handle,
+ lock_handle=handle,
)
return runtime
diff --git a/openviking/service/core.py b/openviking/service/core.py
index ca3964804..98a13f81d 100644
--- a/openviking/service/core.py
+++ b/openviking/service/core.py
@@ -31,6 +31,7 @@ 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,
@@ -87,7 +88,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
@@ -172,7 +173,16 @@ class OpenVikingService:
if self._queue_manager:
self._queue_manager.setup_standard_queues(self._vikingdb_manager, start=False)
- # PathLock has been moved to Rust ragfs; Python-layer LockManager is no longer needed.
+ # 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,
+ )
set_task_tracker(config.build_task_tracker(self._agfs_client))
def _build_ragfs_binding_config(self) -> Any:
@@ -222,6 +232,11 @@ 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."""
@@ -361,6 +376,11 @@ 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,
@@ -417,7 +437,6 @@ class OpenVikingService:
self._resource_service,
asyncio.get_running_loop(),
queue_name,
- self._viking_fs,
),
allow_create=True,
)
@@ -457,6 +476,10 @@ 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 eccde2ee2..d0a8f8625 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.viking_fs import get_viking_fs
-from openviking_cli.utils import run_async
+from openviking.storage.transaction import get_lock_manager
from openviking_cli.utils.config import OpenVikingConfig
from openviking_cli.utils.logger import get_logger
@@ -165,10 +165,9 @@ class ObserverService:
@property
def lock(self) -> ComponentStatus:
- """Get lock system status via pathlock_observe snapshot."""
+ """Get lock system status."""
try:
- viking_fs = get_viking_fs()
- snapshot = run_async(viking_fs._async_agfs.pathlock_observe())
+ lock_manager = get_lock_manager()
except Exception:
return ComponentStatus(
name="lock",
@@ -176,22 +175,12 @@ class ObserverService:
has_errors=True,
status="Not initialized",
)
- 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)}",
- ]
+ observer = LockObserver(lock_manager)
return ComponentStatus(
name="lock",
- is_healthy=not has_errors,
- has_errors=has_errors,
- status="\n".join(lines),
+ is_healthy=observer.is_healthy(),
+ has_errors=observer.has_errors(),
+ status=observer.get_status_table(),
)
@property
@@ -233,8 +222,10 @@ 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 9789a178f..57a261024 100644
--- a/openviking/service/reindex_executor.py
+++ b/openviking/service/reindex_executor.py
@@ -31,6 +31,13 @@ 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
@@ -97,7 +104,7 @@ class _ReindexCounters:
class _ReindexRunContext:
ctx: RequestContext
counters: _ReindexCounters
- lock: dict | None = None
+ lock: LockLease = NO_LOCK
@dataclass
@@ -435,73 +442,71 @@ class ReindexExecutor:
if telemetry_id:
wait_tracker.register_request(telemetry_id)
- lease = await service.viking_fs._async_agfs.pathlock_acquire_tree(path)
try:
- 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,
+ async with LockContext(get_lock_manager(), [path], lock_mode="tree") as lock_handle:
+ run = _ReindexRunContext(
ctx=ctx,
+ counters=counters,
+ lock=BorrowedLockLease.from_handle(get_lock_manager(), lock_handle),
)
- 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)
@@ -911,7 +916,7 @@ class ReindexExecutor:
uri: str,
context_type: str,
ctx: RequestContext,
- lock: dict | None = None,
+ lock: LockLease = NO_LOCK,
) -> None:
processor = SemanticProcessor(
max_concurrent_llm=get_openviking_config().vlm.max_concurrent,
@@ -927,7 +932,7 @@ class ReindexExecutor:
role=str(ctx.role),
skip_vectorization=True,
)
- await processor.on_dequeue({"data": msg.to_json()}, lock=lock)
+ await processor.on_dequeue({"data": msg.to_json()}, lock=lock.as_borrowed())
async def _reindex_resource_vectors(
self,
@@ -1087,8 +1092,7 @@ 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)
- lease = await viking_fs._async_agfs.pathlock_acquire_exact(lock_path)
- try:
+ async with LockContext(get_lock_manager(), [lock_path], lock_mode="exact"):
abstract = await self._read_directory_abstract(dir_uri, ctx=ctx)
if level == ContextLevel.ABSTRACT:
vector_text = abstract
@@ -1110,8 +1114,6 @@ 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 6de710b14..6c762168c 100644
--- a/openviking/service/resource_service.py
+++ b/openviking/service/resource_service.py
@@ -45,6 +45,7 @@ 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
@@ -359,36 +360,33 @@ class ResourceService:
msg: Any,
*,
queue_name: str,
- resource_lock: Optional[Dict[str, Any]] = None,
+ resource_lock: LockLease = NO_LOCK,
) -> Any:
- """Persist a job and fully own the passed lock until handoff or release completes."""
+ """Persist a job before its TaskRecord so a crash cannot orphan the task."""
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())
- if resource_lock is not None:
- await self._viking_fs._async_agfs.pathlock_handoff(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,
- )
+ await resource_lock.handoff()
except BaseException:
- if resource_lock is not None:
- await self._viking_fs._async_agfs.pathlock_release(resource_lock)
+ await resource_lock.close()
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(
@@ -396,10 +394,11 @@ class ResourceService:
msg: Any,
*,
ctx: RequestContext,
- resource_lock: Optional[Dict[str, Any]],
+ resource_lock: Optional[LockLease],
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
@@ -491,15 +490,18 @@ class ResourceService:
self,
root_uri: str,
ctx: RequestContext,
- ) -> Dict[str, Any]:
+ ) -> LockLease:
"""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._viking_fs._async_agfs.pathlock_acquire_tree(
+ return await self._resource_processor.acquire_resource_lock(
+ get_lock_manager(),
dst_path,
- timeout_secs=0.0,
+ uri=root_uri,
+ timeout=0.0,
)
async def enqueue_git_add_resource(
@@ -549,7 +551,7 @@ class ResourceService:
from openviking.storage.queuefs.add_resource_msg import AddResourceMsg
- resource_lock: Optional[Dict[str, Any]] = None
+ resource_lock: LockLease = NO_LOCK
try:
if enforce_public_remote_targets and is_remote_resource_source(path):
path = require_remote_resource_source(path)
@@ -568,11 +570,7 @@ class ResourceService:
)
task_id = str(uuid4())
- lock_handoff = (
- await self._viking_fs._async_agfs.pathlock_to_handoff(resource_lock)
- if resource_lock is not None
- else None
- )
+ lock_handoff = resource_lock.to_handoff()
processor_args = {
key: value
for key, value in kwargs.items()
@@ -587,7 +585,7 @@ class ResourceService:
user_id=ctx.user.user_id,
role=str(ctx.role),
actor_peer_id=ctx.actor_peer_id,
- lock_handoff=lock_handoff,
+ lock_handoff=lock_handoff.to_dict() if lock_handoff else None,
reason=reason,
instruction=instruction,
timeout=timeout,
@@ -608,21 +606,19 @@ class ResourceService:
source_name=source_name,
args=self._sanitize_watch_processor_kwargs(processor_args),
)
- enqueue_lock = resource_lock
- resource_lock = None
task = await self._enqueue_add_resource_job(
msg,
queue_name=QueueManager.ADD_RESOURCE,
- resource_lock=enqueue_lock,
+ resource_lock=resource_lock,
)
+ resource_lock = NO_LOCK
return {
"status": "success",
"root_uri": root_uri,
"task_id": task.task_id,
}
except Exception:
- if resource_lock is not None:
- await self._viking_fs._async_agfs.pathlock_release(resource_lock)
+ await resource_lock.close()
raise
async def _plan_resource_target(
@@ -633,7 +629,7 @@ class ResourceService:
target: ContentTargetSpec,
source_name: Optional[str],
source_info: _ResourceSourceInfo,
- ) -> tuple[str, Optional[Dict[str, Any]]]:
+ ) -> tuple[str, LockLease]:
if not self._resource_processor or not self._viking_fs:
raise NotInitializedError("ResourceProcessor")
@@ -655,10 +651,14 @@ 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._viking_fs._async_agfs.pathlock_acquire_tree(
+ resource_lock = await self._resource_processor.acquire_resource_lock(
+ get_lock_manager(),
dst_path,
- timeout_secs=0.0,
+ uri=root_uri,
+ timeout=0.0,
)
return root_uri, resource_lock
@@ -961,7 +961,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[Dict[str, Any]] = None,
+ resource_lock: Optional[LockLease] = None,
stage_callback: Optional[Callable[[str], Any]] = None,
**kwargs,
) -> Dict[str, Any]:
@@ -972,7 +972,7 @@ class ResourceService:
telemetry_id = register_wait_telemetry(wait)
request_wait_tracker = get_request_wait_tracker()
job_enqueued = False
- deferred_lock: Optional[Dict[str, Any]] = None
+ deferred_lock: LockLease = NO_LOCK
if telemetry_id:
request_wait_tracker.register_request(telemetry_id)
watch_manager = self._get_watch_manager()
@@ -1070,18 +1070,19 @@ class ResourceService:
)
if self._viking_fs is None:
raise NotInitializedError("VikingFS")
- from openviking.storage.errors import ResourceBusyError
+ from openviking.storage.errors import LockAcquisitionError, ResourceBusyError
+ from openviking.storage.transaction import OwnedLockLease, get_lock_manager
- lock_lease: Optional[Dict[str, Any]] = None
+ lock_manager = get_lock_manager()
+ lock_lease: LockLease = NO_LOCK
- async def _reserve_tree(uri: str) -> Dict[str, Any]:
+ async def _reserve_tree(uri: str) -> LockLease:
dst_path = self._viking_fs._uri_to_path(uri, ctx=ctx)
try:
- return await self._viking_fs._async_agfs.pathlock_acquire_tree(
- dst_path,
- timeout_secs=0.0,
+ return await OwnedLockLease.acquire_tree(
+ lock_manager, dst_path, timeout=0.0
)
- except Exception as exc:
+ except LockAcquisitionError as exc:
raise ResourceBusyError(
f"Resource is busy: {uri}",
uri=uri,
@@ -1114,11 +1115,7 @@ class ResourceService:
if resolved_extension:
processor_args["resolved_extension"] = resolved_extension
- lock_handoff = (
- await self._viking_fs._async_agfs.pathlock_to_handoff(lock_lease)
- if lock_lease is not None
- else None
- )
+ lock_handoff = lock_lease.to_handoff()
msg = AddResourceMsg(
task_id=str(uuid4()),
telemetry_id=telemetry_id or None,
@@ -1145,23 +1142,22 @@ class ResourceService:
enforce_public_remote_targets=enforce_public_remote_targets,
args=processor_args,
source_name=source_name,
- lock_handoff=lock_handoff,
+ lock_handoff=lock_handoff.to_dict() if lock_handoff else None,
skip_watch_management=True,
defer_target_resolution=defer_target_resolution,
understanding_response_id=understanding_response_id,
)
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=enqueue_lock,
+ resource_lock=lock_lease,
)
except BaseException:
- if not enqueue_started and lock_lease is not None:
- await self._viking_fs._async_agfs.pathlock_release(lock_lease)
+ if not enqueue_started:
+ await lock_lease.close()
raise
+ lock_lease = NO_LOCK
job_enqueued = True
logger.info(
"[ResourceService] Enqueued AddResourceMsg task_id=%s root_uri=%s",
@@ -1214,7 +1210,7 @@ class ResourceService:
if result.get("status") == "error":
return result
prepared = result.pop("_post_process", None)
- deferred_lock = result.pop("_resource_lock", None)
+ deferred_lock = result.pop("_resource_lock", NO_LOCK)
if wait:
if stage_callback is not None:
stage_result = stage_callback("processing_queue")
@@ -1268,11 +1264,7 @@ class ResourceService:
root_uri = result.get("root_uri", "")
if not isinstance(prepared, dict):
raise InternalError("Deferred resource processing payload is missing")
- lock_handoff = (
- await self._viking_fs._async_agfs.pathlock_to_handoff(deferred_lock)
- if deferred_lock is not None
- else None
- )
+ lock_handoff = deferred_lock.to_handoff()
msg = AddResourceMsg(
task_id=str(uuid4()),
root_uri=root_uri,
@@ -1282,7 +1274,7 @@ class ResourceService:
user_id=ctx.user.user_id,
role=str(ctx.role),
actor_peer_id=ctx.actor_peer_id,
- lock_handoff=lock_handoff,
+ lock_handoff=lock_handoff.to_dict() if lock_handoff else None,
reason=reason,
instruction=instruction,
timeout=timeout,
@@ -1301,13 +1293,12 @@ class ResourceService:
source_name=kwargs.get("source_name"),
skip_watch_management=True,
)
- enqueue_lock = deferred_lock
- deferred_lock = None
task = await self._enqueue_add_resource_job(
msg,
queue_name=QueueManager.ADD_RESOURCE,
- resource_lock=enqueue_lock,
+ resource_lock=deferred_lock,
)
+ deferred_lock = NO_LOCK
result["task_id"] = task.task_id
job_enqueued = True
await self._manage_watch_if_needed(
@@ -1352,8 +1343,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 is not None:
- await self._viking_fs._async_agfs.pathlock_release(deferred_lock)
+ if deferred_lock.active:
+ await deferred_lock.close()
async def _link_resource_reason_memory(
self,
diff --git a/openviking/session/compressor_v2.py b/openviking/session/compressor_v2.py
index 8b19a3705..8322cd048 100644
--- a/openviking/session/compressor_v2.py
+++ b/openviking/session/compressor_v2.py
@@ -179,9 +179,7 @@ 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(
@@ -284,14 +282,17 @@ class SessionCompressorV2:
telemetry.set("memory.extract.deleted", 0)
telemetry.set("memory.extract.skipped", 0)
- from openviking.storage.errors import LockAcquisitionError
+ from openviking.storage.transaction import get_lock_manager, init_lock_manager
- # 初始化锁(仅在有 AGFS 时使用锁机制)
+ # 初始化锁管理器(仅在有 AGFS 时使用锁机制)
viking_fs = get_viking_fs()
- lease = None
+ lock_manager = None
transaction_handle = None
- has_agfs = viking_fs and hasattr(viking_fs, "agfs") and viking_fs.agfs
- if not has_agfs:
+ 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:
logger.debug("AGFS unavailable, running memory extraction without locks")
try:
@@ -329,7 +330,7 @@ class SessionCompressorV2:
context_provider=context_provider,
)
read_scope = isolation_handler.get_read_scope()
- if has_agfs:
+ if lock_manager:
schemas = orchestrator.context_provider.get_memory_schemas(ctx)
exact_lock_paths, tree_lock_dirs = _render_memory_schema_locks(
schemas=schemas,
@@ -349,30 +350,28 @@ class SessionCompressorV2:
# 循环重试获取锁(机制确保不会死锁)
while True:
- try:
- lease = await viking_fs._async_agfs.pathlock_acquire_exact_tree_batch(
- exact_lock_paths,
- tree_lock_dirs,
- timeout_secs=0.1,
- )
+ 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:
break
- 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,
+ 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})"
)
- if retry_interval > 0:
- await asyncio.sleep(retry_interval)
- transaction_handle = lease
+ 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)
orchestrator._transaction_handle = transaction_handle # 传递给 ExtractLoop
@@ -470,12 +469,12 @@ class SessionCompressorV2:
raise
return []
finally:
- # 确保释放所有锁
- if lease is not None:
+ # 确保释放所有锁(仅在有锁管理器时)
+ if lock_manager and transaction_handle:
try:
- await viking_fs._async_agfs.pathlock_release(lease)
+ await lock_manager.release(transaction_handle)
except Exception as e:
- logger.warning(f"Failed to release pathlock: {e}")
+ logger.warning(f"Failed to release transaction lock: {e}")
@staticmethod
def _empty_memory_diff(archive_uri: str = "") -> Dict[str, Any]:
@@ -593,7 +592,7 @@ class SessionCompressorV2:
async def _append_sources_before_unlock(
result: MemoryUpdateResult,
inheritance_map: Dict[str, List[str]],
- lease_ref: Any,
+ lock_handle: Any,
exp_provider=exp_provider,
exp_dir=exp_dir,
traj_uri=traj_uri,
@@ -613,7 +612,7 @@ class SessionCompressorV2:
source_uris,
ctx,
viking_fs,
- lease_ref=lease_ref,
+ lock_handle=lock_handle,
)
exp_result = await self._run_extract_phase(
@@ -733,7 +732,7 @@ class SessionCompressorV2:
Returns None on failure (unless strict_extract_errors is True, in which case
the exception is re-raised).
"""
- from openviking.storage.errors import LockAcquisitionError
+ from openviking.storage.transaction import get_lock_manager, init_lock_manager
config = get_openviking_config()
vlm = config.vlm.get_vlm_instance()
@@ -765,12 +764,15 @@ class SessionCompressorV2:
thinking=thinking,
)
- lease = None
+ lock_manager = None
transaction_handle = None
- has_agfs = viking_fs and hasattr(viking_fs, "agfs") and viking_fs.agfs
+ 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()
try:
- if has_agfs:
+ if lock_manager:
schemas = [
schema
for schema in provider.get_memory_schemas(ctx)
@@ -790,30 +792,28 @@ class SessionCompressorV2:
retry_count = 0
last_lock_retry_warning_at = 0.0
while True:
- try:
- lease = await viking_fs._async_agfs.pathlock_acquire_exact_tree_batch(
- exact_lock_paths,
- tree_lock_dirs,
- timeout_secs=0.1,
- )
+ 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:
break
- 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,
+ 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})"
)
- if retry_interval > 0:
- await asyncio.sleep(retry_interval)
-
- transaction_handle = lease
+ 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)
provider._transaction_handle = transaction_handle
orchestrator._transaction_handle = transaction_handle
@@ -916,11 +916,11 @@ class SessionCompressorV2:
raise
return None
finally:
- if lease is not None:
+ if lock_manager and transaction_handle:
try:
- await viking_fs._async_agfs.pathlock_release(lease)
+ await lock_manager.release(transaction_handle)
except Exception as e:
- logger.warning(f"[{phase_label}] Failed to release pathlock: {e}")
+ logger.warning(f"[{phase_label}] Failed to release transaction lock: {e}")
async def _resolve_supersedes(
self,
@@ -997,7 +997,7 @@ class SessionCompressorV2:
traj_uris: List[str],
ctx,
viking_fs,
- lease_ref: Optional[Any] = None,
+ lock_handle: Optional[Any] = None,
) -> None:
"""Write bidirectional StoredLinks between traj_uris and each exp file.
@@ -1010,28 +1010,33 @@ class SessionCompressorV2:
for exp_uri in exp_uris:
try:
- 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
-
try:
+ from openviking.storage.transaction import LockContext, get_lock_manager
+
+ 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:
await self._append_trajectory_metadata(
exp_uri,
normalized_traj_uris,
ctx,
viking_fs,
- lease_ref=lease,
+ lock_handle=active_lock_handle,
)
- 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}")
@@ -1041,7 +1046,7 @@ class SessionCompressorV2:
traj_uris: List[str],
ctx,
viking_fs,
- lease_ref=None,
+ lock_handle=None,
) -> None:
from datetime import timezone
@@ -1065,11 +1070,12 @@ 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,
- lease_ref=lease_ref,
+ lock_handle=lock_handle,
)
tracer.info(
f"[agent_link] wrote exp→traj links -> {exp_uri} (traj_count={len(traj_uris)})"
@@ -1078,7 +1084,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}, lease_ref=lease_ref)
+ await write_stored_links(links, ctx, viking_fs, skip_uris={exp_uri})
async def _build_memory_diff(
self,
diff --git a/openviking/session/compressor_v3.py b/openviking/session/compressor_v3.py
index dc5659c6f..95e611a5a 100644
--- a/openviking/session/compressor_v3.py
+++ b/openviking/session/compressor_v3.py
@@ -184,6 +184,7 @@ 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 2cd9da81e..7596fdc80 100644
--- a/openviking/session/memory/memory_updater.py
+++ b/openviking/session/memory/memory_updater.py
@@ -76,13 +76,14 @@ async def write_stored_links(
ctx: RequestContext,
viking_fs: Any,
skip_uris: Optional[set] = None,
- lease_ref: Any = None,
+ lock_handle: 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.
@@ -90,6 +91,7 @@ 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:
@@ -120,7 +122,7 @@ async def write_stored_links(
uri,
MemoryFileUtils.write(mf),
ctx=ctx,
- lease_ref=lease_ref,
+ **lock_kwargs,
)
updated_uris.append(uri)
except Exception as e:
@@ -128,6 +130,7 @@ 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:
@@ -149,7 +152,6 @@ 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
@@ -291,7 +293,6 @@ 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)
@@ -303,7 +304,6 @@ 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,7 +315,6 @@ 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)
@@ -712,12 +711,8 @@ class MemoryUpdater:
"""
def __init__(
- self,
- registry: Optional[MemoryTypeRegistry] = None,
- vikingdb=None,
- transaction_handle: Any = None,
+ self, registry: Optional[MemoryTypeRegistry] = None, vikingdb=None, transaction_handle=None
):
- """Create a memory updater with an optional pathlock transaction handle."""
self._viking_fs = None
self._registry = registry
self._vikingdb = vikingdb
@@ -851,7 +846,6 @@ 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():
@@ -872,12 +866,7 @@ class MemoryUpdater:
list(getattr(operations, "resolved_links", []) or []),
dict(getattr(operations, "delete_replacements", {}) or {}),
)
- await self._inherit_deleted_link_relations(
- operations,
- result,
- ctx,
- lease_ref=self._transaction_handle,
- )
+ await self._inherit_deleted_link_relations(operations, result, ctx)
# Apply delete operations (delete_file_contents is List[MemoryFile])
# Skip deletes whose URI was just written in the same batch — this happens when the
@@ -907,13 +896,13 @@ class MemoryUpdater:
)
continue
try:
- await self._apply_delete(delete_uri, ctx, lease_ref=self._transaction_handle)
+ await self._apply_delete(delete_uri, ctx)
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, lease_ref=self._transaction_handle)
+ await self._sync_resource_refs_for_result(result, ctx)
# Vectorize written and edited memories
uri_memory_type_map = {}
@@ -934,7 +923,6 @@ class MemoryUpdater:
result,
ctx,
deleted_uris=set(result.deleted_uris),
- lease_ref=self._transaction_handle,
)
tracer.info(f"Memory operations applied: {result.summary()}")
@@ -955,13 +943,7 @@ class MemoryUpdater:
)
for dir, memory_type in dirs.items():
- await self.generate_overview(
- memory_type,
- dir,
- ctx,
- extract_context,
- lease_ref=self._transaction_handle,
- )
+ await self.generate_overview(memory_type, dir, ctx, extract_context)
return result
@@ -969,7 +951,6 @@ 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()
@@ -993,17 +974,13 @@ class MemoryUpdater:
uri,
MemoryFileUtils.write(mf),
ctx=ctx,
- lease_ref=lease_ref,
+ lock_handle=self._transaction_handle,
)
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,
- lease_ref: Any = None,
+ self, resolved_op: ResolvedOperation, ctx: RequestContext, extract_context: Any = None
):
"""Apply upsert operation from a flat model."""
viking_fs = self._get_viking_fs()
@@ -1119,7 +1096,7 @@ class MemoryUpdater:
uri,
new_full_content,
ctx=ctx,
- lease_ref=lease_ref,
+ lock_handle=self._transaction_handle,
)
def _distribute_links_to_operations(self, operations: ResolvedOperations) -> None:
@@ -1156,7 +1133,6 @@ 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()
@@ -1177,15 +1153,15 @@ class MemoryUpdater:
ctx,
viking_fs,
skip_uris=skip,
- lease_ref=lease_ref,
+ lock_handle=self._transaction_handle,
)
+
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:
@@ -1203,9 +1179,7 @@ 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
@@ -1262,25 +1236,22 @@ class MemoryUpdater:
uri,
MemoryFileUtils.write(mf),
ctx=ctx,
- lease_ref=lease_ref,
+ lock_handle=self._transaction_handle,
)
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,
- lease_ref: Any = None,
- ) -> None:
+ async def _apply_delete(self, uri: str, ctx: RequestContext) -> None:
"""Apply delete operation (uri is already a string)."""
viking_fs = self._get_viking_fs()
# Delete from VikingFS
- # VikingFS automatically handles vector index cleanup.
+ # 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).
try:
- await viking_fs.rm(uri, recursive=False, ctx=ctx, lease_ref=lease_ref)
+ await viking_fs.rm(uri, recursive=False, ctx=ctx, lock_handle=self._transaction_handle)
except NotFoundError:
tracer.error(f"Memory not found for delete: {uri}")
# Idempotent - deleting non-existent file succeeds
@@ -1426,7 +1397,6 @@ 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.
@@ -1483,7 +1453,7 @@ class MemoryUpdater:
overview_path,
recursive=False,
ctx=ctx,
- lease_ref=lease_ref,
+ lock_handle=self._transaction_handle,
)
except Exception:
pass
@@ -1494,7 +1464,7 @@ class MemoryUpdater:
directory,
recursive=True,
ctx=ctx,
- lease_ref=lease_ref,
+ lock_handle=self._transaction_handle,
)
except Exception:
pass
@@ -1549,7 +1519,7 @@ class MemoryUpdater:
overview_path,
rendered,
ctx=ctx,
- lease_ref=lease_ref,
+ lock_handle=self._transaction_handle,
)
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 4453463f0..540cc1432 100644
--- a/openviking/session/memory/streaming_memory_updater.py
+++ b/openviking/session/memory/streaming_memory_updater.py
@@ -442,6 +442,7 @@ 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 2bbd76479..b28a8745e 100644
--- a/openviking/session/session.py
+++ b/openviking/session/session.py
@@ -696,8 +696,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, lease_ref: Optional[Any] = None) -> None:
- """Persist .meta.json to storage using an optional held PathLock lease."""
+ async def _save_meta(self) -> None:
+ """Persist .meta.json to storage."""
if not self._viking_fs:
return
self._meta.updated_at = get_current_timestamp()
@@ -705,7 +705,6 @@ 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
@@ -1124,11 +1123,15 @@ 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)
- lease = await self._viking_fs._async_agfs.pathlock_acquire_tree(
- session_path, timeout_secs=_SESSION_PHASE1_LOCK_TIMEOUT_SECONDS
- )
- try:
+ async with LockContext(
+ get_lock_manager(),
+ [session_path],
+ lock_mode="exact",
+ timeout=_SESSION_PHASE1_LOCK_TIMEOUT_SECONDS,
+ ):
self._messages = await self._read_live_messages_strict()
in_memory_meta = self._meta
try:
@@ -1148,11 +1151,8 @@ class Session:
f"{self._session_uri}/messages.jsonl",
batch_content,
ctx=self.ctx,
- lease_ref=lease,
)
- await self._save_meta(lease_ref=lease)
- finally:
- await self._viking_fs._async_agfs.pathlock_release(lease)
+ await self._save_meta()
async def _append_messages_without_path_lock(self, messages: List[Message]) -> None:
"""Compatibility append for storage adapters without path locking."""
@@ -1418,12 +1418,7 @@ 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],
- lease_ref: Optional[Any] = None,
- ) -> None:
+ async def _merge_archive_meta(self, archive_uri: str, updates: Dict[str, Any]) -> None:
"""Merge archive metadata so Phase 2 cannot erase Phase 1 planning data."""
if not self._viking_fs:
return
@@ -1444,7 +1439,6 @@ class Session:
uri=f"{archive_uri}/.meta.json",
content=json.dumps(meta, ensure_ascii=False),
ctx=self.ctx,
- lease_ref=lease_ref,
)
@staticmethod
@@ -1483,7 +1477,6 @@ 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 = {
@@ -1509,15 +1502,9 @@ class Session:
"skip_reason": agent_memory_skip_reason,
},
},
- lease_ref=lease_ref,
)
- 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."""
+ async def _write_phase1_ready_marker(self, archive_uri: str) -> None:
phase1 = await self._read_phase1_meta(archive_uri)
phase1.update(
{
@@ -1525,7 +1512,7 @@ class Session:
"ready_at": get_current_timestamp(),
}
)
- await self._merge_archive_meta(archive_uri, {"phase1": phase1}, lease_ref=lease_ref)
+ await self._merge_archive_meta(archive_uri, {"phase1": phase1})
async def _archive_file_exists(self, archive_uri: str, file_name: str) -> bool:
try:
@@ -1555,11 +1542,15 @@ 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)
- lease = await self._viking_fs._async_agfs.pathlock_acquire_tree(
- session_path, timeout_secs=_SESSION_PHASE1_LOCK_TIMEOUT_SECONDS
- )
- try:
+ async with LockContext(
+ get_lock_manager(),
+ [session_path],
+ lock_mode="exact",
+ timeout=_SESSION_PHASE1_LOCK_TIMEOUT_SECONDS,
+ ):
marker = await self._read_phase1_meta(archive_uri)
if marker.get("status") == "ready":
return True
@@ -1581,21 +1572,20 @@ 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
@@ -1613,7 +1603,9 @@ 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)
),
@@ -1626,12 +1618,10 @@ class Session:
)
self._meta.last_commit_at = get_current_timestamp()
self._rebuild_pending_tokens()
- await self._save_meta(lease_ref=lease)
- await self._write_phase1_ready_marker(archive_uri, lease_ref=lease)
+ await self._save_meta()
+ await self._write_phase1_ready_marker(archive_uri)
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,
@@ -1687,6 +1677,7 @@ 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))
@@ -1742,10 +1733,12 @@ 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)
- lease = await self._viking_fs._async_agfs.pathlock_acquire_tree(
- session_path, timeout_secs=_SESSION_PHASE1_LOCK_TIMEOUT_SECONDS
- )
- try:
+ async with LockContext(
+ get_lock_manager(),
+ [session_path],
+ lock_mode="exact",
+ timeout=_SESSION_PHASE1_LOCK_TIMEOUT_SECONDS,
+ ):
self._messages = await self._read_live_messages_strict()
try:
meta_content = await self._viking_fs.read_file(
@@ -1797,7 +1790,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(lease_ref=lease)
+ await self._save_meta()
get_current_telemetry().set("memory.extracted", 0)
return {
"session_id": self.session_id,
@@ -1837,7 +1830,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, lease_ref=lease)
+ await self._write_to_agfs_async(messages=self._messages)
self._meta.pending_tokens = 0
self._meta.message_count = total
self._remember_retention_policy(
@@ -1847,7 +1840,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(lease_ref=lease)
+ await self._save_meta()
get_current_telemetry().set("memory.extracted", 0)
return {
"session_id": self.session_id,
@@ -1898,7 +1891,6 @@ 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
@@ -1909,7 +1901,6 @@ 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(
@@ -1922,7 +1913,6 @@ class Session:
min_raw_tail_steps=effective_min_tail,
)
},
- lease_ref=lease,
)
phase1_stage = "queue_enqueue"
@@ -1947,7 +1937,7 @@ class Session:
phase1_stage = "phase1_persist"
self._messages = retained_messages
- await self._write_to_agfs_async(messages=self._messages, lease_ref=lease)
+ await self._write_to_agfs_async(messages=self._messages)
self._meta.message_count = len(self._messages)
self._meta.pending_tokens = 0
self._remember_retention_policy(
@@ -1962,8 +1952,8 @@ class Session:
self._compression.compression_index,
)
self._meta.last_commit_at = get_current_timestamp()
- await self._save_meta(lease_ref=lease)
- await self._write_phase1_ready_marker(archive_uri, lease_ref=lease)
+ await self._save_meta()
+ await self._write_phase1_ready_marker(archive_uri)
except Exception as e:
logger.error(f"[commit] Failed during {phase1_stage}: {e}")
# Whether the queue write failed or a queued Phase 1 stopped
@@ -1974,7 +1964,6 @@ class Session:
archive_uri,
stage=phase1_stage,
error=str(e),
- lease_ref=lease,
)
except Exception:
logger.exception(
@@ -1984,8 +1973,6 @@ 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.
@@ -2105,17 +2092,23 @@ 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,
@@ -2701,7 +2694,6 @@ 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:
@@ -2719,7 +2711,6 @@ 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]:
@@ -3390,7 +3381,9 @@ 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
@@ -3408,7 +3401,9 @@ 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
@@ -3492,7 +3487,9 @@ 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:
@@ -3583,11 +3580,15 @@ 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)
- lease = await self._viking_fs._async_agfs.pathlock_acquire_tree(
- session_path, timeout_secs=_SESSION_PHASE1_LOCK_TIMEOUT_SECONDS
- )
- try:
+ async with LockContext(
+ get_lock_manager(),
+ [session_path],
+ lock_mode="exact",
+ timeout=_SESSION_PHASE1_LOCK_TIMEOUT_SECONDS,
+ ):
latest_meta = self._meta
try:
meta_content = await self._viking_fs.read_file(
@@ -3621,9 +3622,7 @@ 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(lease_ref=lease)
- finally:
- await self._viking_fs._async_agfs.pathlock_release(lease)
+ await self._save_meta()
async def _read_live_message_count(self) -> int:
"""Count current live session messages from persisted storage."""
@@ -4810,12 +4809,8 @@ class Session:
return "\n".join(parts).rstrip() + "\n"
- 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."""
+ async def _write_to_agfs_async(self, messages: List[Message]) -> None:
+ """Write messages.jsonl to AGFS (async)."""
if not self._viking_fs:
return
@@ -4832,19 +4827,16 @@ 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 897ac3ccf..a43f3ac0e 100644
--- a/openviking/session/train/components/policy_updater.py
+++ b/openviking/session/train/components/policy_updater.py
@@ -130,7 +130,9 @@ 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)
@@ -223,6 +225,7 @@ 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,
@@ -244,7 +247,8 @@ def _plan_to_resolved_operations(
!= _normalize_guard_content(item.before_content)
):
errors.append(
- f"base content mismatch for {item.target_name}: expected gradient before_content"
+ "base content mismatch for "
+ f"{item.target_name}: expected gradient before_content"
)
continue
@@ -260,7 +264,9 @@ 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 500341840..2bea52390 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, lease_ref=transaction_handle)
+ await viking_fs.rm(skill_root, ctx=ctx, lock_handle=transaction_handle)
deleted_uris.append(old_file.uri)
except Exception as exc:
delete_errors.append(f"{old_file.uri}: {exc}")
@@ -138,7 +138,9 @@ 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)
@@ -237,7 +239,9 @@ 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 6e66158bf..b7348952c 100644
--- a/openviking/session/train/domain.py
+++ b/openviking/session/train/domain.py
@@ -80,12 +80,19 @@ 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)
- lease = await self.viking_fs._async_agfs.pathlock_acquire_tree(path, timeout_secs=300.0)
+ 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}")
try:
- yield lease
+ yield handle
finally:
- await self.viking_fs._async_agfs.pathlock_release(lease)
+ await lock_manager.release(handle)
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 6a4a776ce..304eea4c6 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 Any, Dict, Optional
+from typing import TYPE_CHECKING, Any, Dict, Optional
from openviking.core.namespace import (
NamespaceShapeError,
@@ -27,9 +27,10 @@ from openviking.session.memory.utils.resource_refs import (
RESOURCE_REF_SOURCE_CONTENT_WRITE,
sync_memory_resource_refs,
)
-from openviking.storage.errors import LockAcquisitionError, ResourceBusyError
+from openviking.storage.errors import 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
@@ -50,19 +51,12 @@ 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
@@ -160,14 +154,16 @@ 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)
- try:
- lease = await self._viking_fs._async_agfs.pathlock_acquire_tree(root_path)
- except LockAcquisitionError as exc:
+ acquired = await lock_manager.acquire_tree(handle, root_path)
+ if not acquired:
+ await lock_manager.release(handle)
raise ResourceBusyError(
f"resource is busy and cannot be written now: {normalized_root}",
uri=normalized_root,
- ) from exc
+ )
created: list[str] = []
updated: list[str] = []
@@ -230,7 +226,7 @@ class ContentWriteCoordinator:
uri,
operation["content"],
ctx=ctx,
- lease_ref=lease,
+ lock_handle=handle,
)
except Exception as exc:
write_error = exc
@@ -242,7 +238,7 @@ class ContentWriteCoordinator:
created.append(uri)
refresh_kinds[uri] = "added"
finally:
- await self._viking_fs._async_agfs.pathlock_release(lease)
+ await lock_manager.release(handle)
lock_released = True
assert lock_released
@@ -693,14 +689,16 @@ 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)
- try:
- lease = await self._viking_fs._async_agfs.pathlock_acquire_exact(lock_path)
- except LockAcquisitionError as exc:
+ acquired = await lock_manager.acquire_exact_path(handle, lock_path)
+ if not acquired:
+ await lock_manager.release(handle)
raise ResourceBusyError(
f"resource is busy and cannot be written now: {uri}",
uri=uri,
- ) from exc
+ )
previous_content: Optional[str] = None
content_written = False
@@ -711,7 +709,13 @@ 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, lease_ref=lease)
+ await self._write_in_place(
+ uri,
+ content,
+ mode=mode,
+ ctx=ctx,
+ lock_handle=handle,
+ )
content_written = True
await self._enqueue_semantic_refresh(
root_uri=root_uri,
@@ -721,7 +725,7 @@ class ContentWriteCoordinator:
change_type="added" if mode == "create" else "modified",
)
semantic_enqueued = True
- await self._viking_fs._async_agfs.pathlock_release(lease)
+ await lock_manager.release(handle)
lock_released = True
queue_status = (
await self._wait_for_request(telemetry_id=telemetry_id, timeout=timeout)
@@ -744,10 +748,10 @@ class ContentWriteCoordinator:
previous_content=previous_content,
mode=mode,
ctx=ctx,
- lease_ref=lease,
+ lock_handle=handle,
)
if not lock_released:
- await self._viking_fs._async_agfs.pathlock_release(lease)
+ await lock_manager.release(handle)
raise
finally:
if wait and telemetry_id:
@@ -760,18 +764,18 @@ class ContentWriteCoordinator:
previous_content: Optional[str],
mode: str,
ctx: RequestContext,
- lease_ref: Optional[Dict[str, Any]] = None,
+ lock_handle: Any,
) -> None:
try:
if mode == "create":
- await self._viking_fs.rm(uri, ctx=ctx, lease_ref=lease_ref)
+ await self._viking_fs.rm(uri, ctx=ctx, lock_handle=lock_handle)
return
if previous_content is not None:
await self._viking_fs.write_file(
uri,
previous_content,
ctx=ctx,
- lease_ref=lease_ref,
+ lock_handle=lock_handle,
)
except Exception:
logger.error("Failed to rollback direct content write for %s", uri, exc_info=True)
@@ -881,7 +885,7 @@ class ContentWriteCoordinator:
*,
mode: str,
ctx: RequestContext,
- lease_ref: Optional[Dict[str, Any]] = None,
+ lock_handle: Optional["LockHandle"] = None,
) -> None:
if context_type_for_uri(uri) == "memory":
if mode == "replace":
@@ -899,7 +903,7 @@ class ContentWriteCoordinator:
uri,
MemoryFileUtils.write(mf),
ctx=ctx,
- lease_ref=lease_ref,
+ lock_handle=lock_handle,
)
return
@@ -908,9 +912,14 @@ 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, lease_ref=lease_ref)
+ await self._viking_fs.write_file(
+ uri,
+ updated_raw,
+ ctx=ctx,
+ lock_handle=lock_handle,
+ )
return
- await self._viking_fs.write_file(uri, content, ctx=ctx, lease_ref=lease_ref)
+ await self._viking_fs.write_file(uri, content, ctx=ctx, lock_handle=lock_handle)
async def _enqueue_semantic_refresh(
self,
@@ -968,20 +977,28 @@ 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)
- try:
- lease = await self._viking_fs._async_agfs.pathlock_acquire_exact(lock_path)
- except LockAcquisitionError as exc:
+ acquired = await lock_manager.acquire_exact_path(handle, lock_path)
+ if not acquired:
+ await lock_manager.release(handle)
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, lease_ref=lease)
- await self._viking_fs._async_agfs.pathlock_release(lease)
+ await self._write_in_place(
+ uri,
+ content,
+ mode=mode,
+ ctx=ctx,
+ lock_handle=handle,
+ )
+ await lock_manager.release(handle)
released = True
if wait and telemetry_id and self._vikingdb_has_queue():
get_request_wait_tracker().register_request(telemetry_id)
@@ -1024,7 +1041,7 @@ class ContentWriteCoordinator:
)
except Exception:
if not released:
- await self._viking_fs._async_agfs.pathlock_release(lease)
+ await lock_manager.release(handle)
raise
finally:
if request_registered:
diff --git a/openviking/storage/observers/__init__.py b/openviking/storage/observers/__init__.py
index 841cd7144..b95548026 100644
--- a/openviking/storage/observers/__init__.py
+++ b/openviking/storage/observers/__init__.py
@@ -2,6 +2,7 @@
# 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
@@ -10,6 +11,7 @@ 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
new file mode 100644
index 000000000..1e7bc5e81
--- /dev/null
+++ b/openviking/storage/observers/lock_observer.py
@@ -0,0 +1,74 @@
+# 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 771c2102b..05fb0edbf 100644
--- a/openviking/storage/queuefs/add_resource_processor.py
+++ b/openviking/storage/queuefs/add_resource_processor.py
@@ -29,19 +29,21 @@ 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 self._viking_fs._async_agfs.pathlock_adopt(msg.lock_handoff)
+ return await OwnedLockLease.from_handoff(ref)
except Exception as handoff_error:
try:
return await self._resource_service.reacquire_add_resource_job_lock(
@@ -177,7 +179,7 @@ class AddResourceProcessor(DequeueHandlerBase):
finally:
with suppress(Exception):
if resource_lock is not None:
- await self._viking_fs._async_agfs.pathlock_release(resource_lock)
+ await resource_lock.close()
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 ab40306d2..2006d9875 100644
--- a/openviking/storage/queuefs/semantic_dag.py
+++ b/openviking/storage/queuefs/semantic_dag.py
@@ -5,11 +5,12 @@
import asyncio
import threading
from dataclasses import dataclass, field
-from typing import Any, ClassVar, Dict, List, Optional, Set
+from typing import ClassVar, Dict, List, Optional, Set
from weakref import WeakKeyDictionary
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
@@ -166,7 +167,7 @@ class SemanticDagExecutor:
semantic_msg_id: Optional[str] = None,
telemetry_id: str = "",
recursive: bool = True,
- lock: Optional[Dict[str, Any]] = None,
+ lock: LockLease = NO_LOCK,
is_code_repo: bool = False,
changes: Optional[Dict[str, List[str]]] = None,
skip_vectorization: bool = False,
@@ -225,12 +226,15 @@ class SemanticDagExecutor:
if self._failure:
raise self._failure
- # Mark semantic done after downstream vectorization finishes.
+ # Release owned semantic locks after downstream vectorization finishes.
async def wrapped_on_complete() -> None:
- if self._telemetry_id and self._semantic_msg_id:
- get_request_wait_tracker().mark_semantic_done(
- self._telemetry_id, self._semantic_msg_id
- )
+ 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()
async with self._vectorize_lock:
task_count = self._vectorize_task_count
@@ -256,6 +260,10 @@ 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 cd82e96d2..f6e059920 100644
--- a/openviking/storage/queuefs/semantic_lock.py
+++ b/openviking/storage/queuefs/semantic_lock.py
@@ -5,20 +5,25 @@
from __future__ import annotations
from dataclasses import dataclass
-from typing import Any, Callable, Dict, Iterable, Optional
+from typing import Callable, Iterable, Optional
from openviking.storage.errors import LockAcquisitionError
-from openviking.storage.internal_names import MULTIWRITE_PATH_LOCK_FILE
-from openviking.storage.viking_fs import get_viking_fs
+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_cli.utils.logger import get_logger
logger = get_logger(__name__)
-_TREE_LOCK_SUFFIX = f"/{MULTIWRITE_PATH_LOCK_FILE}"
+_TREE_LOCK_SUFFIX = f"/{LOCK_FILE_NAME}"
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):
@@ -33,48 +38,52 @@ def _tree_paths_from_handoff(lock_paths: Iterable[str]) -> list[str]:
class SemanticLockScope:
"""Resolved lock scope for one semantic message."""
- lock: Optional[Dict[str, Any]] # lease dict or None
- _owned: bool = False # True when this scope owns the lease (must release)
+ lock: LockLease
@classmethod
async def resolve(
cls,
- lock_handoff: Optional[Dict[str, Any]],
+ lock_handoff: Optional[LockHandoffRef],
*,
- caller_lock: Optional[Dict[str, Any]] = None,
+ caller_lock: LockLease = NO_LOCK,
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 is not None:
+ if lock_handoff and caller_lock.active:
raise ValueError("semantic lock must come from either message or caller, not both")
- 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 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 lock_handoff:
- viking_fs = get_viking_fs()
+ manager = get_lock_manager()
try:
- 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"])
+ return cls(await OwnedLockLease.from_handoff(lock_handoff, manager=manager))
+ except LockAcquisitionError as exc:
+ 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:
- lease = await viking_fs._async_agfs.pathlock_acquire_tree(tree_paths[0])
+ acquired = await manager.acquire_tree(handle, tree_paths[0])
else:
- lease = await viking_fs._async_agfs.pathlock_acquire_tree_batch(tree_paths)
+ 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
logger.info(
"Recovered semantic lock handoff %s by reacquiring %s",
- lock_handoff.get("owner_id"),
+ lock_handoff.handle_id,
tree_paths,
)
- return cls(lease, _owned=True)
- return cls(None)
+ return cls(OwnedLockLease.from_handle(manager, handle))
+ return cls(NO_LOCK)
async def close(self) -> None:
- """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)
+ await self.lock.close()
diff --git a/openviking/storage/queuefs/semantic_msg.py b/openviking/storage/queuefs/semantic_msg.py
index 80303e6bd..a71a77161 100644
--- a/openviking/storage/queuefs/semantic_msg.py
+++ b/openviking/storage/queuefs/semantic_msg.py
@@ -8,6 +8,8 @@ from datetime import datetime
from typing import Any, Dict, List, Optional
from uuid import uuid4
+from openviking.storage.transaction import LockHandoffRef
+
def build_semantic_coalesce_key(
*,
@@ -50,7 +52,7 @@ class SemanticMsg:
skip_vectorization: bool = False
telemetry_id: str = ""
target_uri: str = ""
- lock_handoff: Optional[Dict[str, Any]] = None
+ lock_handoff: Optional[LockHandoffRef] = None
is_code_repo: bool = False
target_preexisting: Optional[bool] = None
coalesce_key: str = ""
@@ -71,7 +73,7 @@ class SemanticMsg:
skip_vectorization: bool = False,
telemetry_id: str = "",
target_uri: str = "",
- lock_handoff: Optional[Dict[str, Any]] = None,
+ lock_handoff: Optional[LockHandoffRef] = None,
is_code_repo: bool = False,
target_preexisting: Optional[bool] = None,
coalesce_key: str = "",
@@ -132,7 +134,7 @@ class SemanticMsg:
skip_vectorization=data.get("skip_vectorization", False),
telemetry_id=data.get("telemetry_id", ""),
target_uri=data.get("target_uri", ""),
- lock_handoff=data.get("lock_handoff"),
+ lock_handoff=LockHandoffRef.from_value(data.get("lock_handoff")),
is_code_repo=data.get("is_code_repo", False),
target_preexisting=data.get("target_preexisting"),
coalesce_key=data.get("coalesce_key", ""),
diff --git a/openviking/storage/queuefs/semantic_processor.py b/openviking/storage/queuefs/semantic_processor.py
index a7175ebeb..016a03e15 100644
--- a/openviking/storage/queuefs/semantic_processor.py
+++ b/openviking/storage/queuefs/semantic_processor.py
@@ -39,6 +39,7 @@ 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
@@ -305,7 +306,7 @@ class SemanticProcessor(DequeueHandlerBase):
async def on_dequeue(
self,
data: Optional[Dict[str, Any]],
- lock: Optional[Dict[str, Any]] = None,
+ lock: LockLease = NO_LOCK,
) -> Optional[Dict[str, Any]]:
"""Process dequeued SemanticMsg, recursively process all subdirectories."""
msg: Optional[SemanticMsg] = None
@@ -371,8 +372,10 @@ 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,
@@ -440,6 +443,7 @@ 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,
@@ -449,7 +453,8 @@ class SemanticProcessor(DequeueHandlerBase):
if not executor.stale:
await self._enqueue_parent_refresh(msg, target_uri or msg.uri)
finally:
- await semantic_lock.close()
+ if not lock_transferred:
+ 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()
@@ -516,7 +521,7 @@ class SemanticProcessor(DequeueHandlerBase):
self,
msg: SemanticMsg,
ctx: Optional[RequestContext] = None,
- lock: Optional[Dict[str, Any]] = None,
+ lock: LockLease = NO_LOCK,
) -> None:
"""Process a memory directory with special handling.
@@ -710,7 +715,7 @@ class SemanticProcessor(DequeueHandlerBase):
)
logger.info(f"Vectorized abstract.md and overview.md for {dir_uri}")
finally:
- pass
+ await lock.close()
async def _write_memory_directory_semantics(
self,
@@ -721,7 +726,7 @@ class SemanticProcessor(DequeueHandlerBase):
overview: str,
abstract: str,
ctx: Optional[RequestContext],
- lock: Optional[Dict[str, Any]] = None,
+ lock: LockLease = NO_LOCK,
) -> bool:
return await write_semantic_sidecars(
viking_fs=viking_fs,
@@ -740,7 +745,7 @@ class SemanticProcessor(DequeueHandlerBase):
target_uri: str,
ctx: Optional[RequestContext] = None,
file_change_status: Optional[Dict[str, bool]] = None,
- lock: Optional[Dict[str, Any]] = None,
+ lock: LockLease = NO_LOCK,
) -> DiffResult:
viking_fs = get_viking_fs()
if not await viking_fs.exists(root_uri, ctx=ctx):
@@ -748,6 +753,7 @@ 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] = {}
@@ -785,7 +791,7 @@ class SemanticProcessor(DequeueHandlerBase):
target_conflict_dir,
recursive=True,
ctx=ctx,
- lease_ref=lock,
+ lock_handle=lock_handle,
)
diff.deleted_dirs.append(target_conflict_dir)
target_dirs.pop(name, None)
@@ -797,7 +803,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, lease_ref=lock)
+ await viking_fs.rm(target_file, ctx=ctx, lock_handle=lock_handle)
diff.deleted_files.append(target_file)
target_files.pop(name, None)
except Exception as e:
@@ -808,7 +814,7 @@ class SemanticProcessor(DequeueHandlerBase):
if target_file and not root_file:
try:
- await viking_fs.rm(target_file, ctx=ctx, lease_ref=lock)
+ await viking_fs.rm(target_file, ctx=ctx, lock_handle=lock_handle)
diff.deleted_files.append(target_file)
except Exception as e:
logger.error(f"[SyncDiff] Failed to delete file: {target_file}, error={e}")
@@ -831,7 +837,7 @@ class SemanticProcessor(DequeueHandlerBase):
if changed:
diff.updated_files.append(target_file)
try:
- await viking_fs.rm(target_file, ctx=ctx, lease_ref=lock)
+ await viking_fs.rm(target_file, ctx=ctx, lock_handle=lock_handle)
except Exception as e:
logger.error(
f"[SyncDiff] Failed to remove old file before update: {target_file}, error={e}"
@@ -841,7 +847,7 @@ class SemanticProcessor(DequeueHandlerBase):
root_file,
target_file,
ctx=ctx,
- lease_ref=lock,
+ lock_handle=lock_handle,
)
except Exception as e:
logger.error(
@@ -857,7 +863,7 @@ class SemanticProcessor(DequeueHandlerBase):
root_file,
target_file_uri,
ctx=ctx,
- lease_ref=lock,
+ lock_handle=lock_handle,
)
except Exception as e:
logger.error(
@@ -875,7 +881,7 @@ class SemanticProcessor(DequeueHandlerBase):
await viking_fs.rm(
target_conflict_file,
ctx=ctx,
- lease_ref=lock,
+ lock_handle=lock_handle,
)
diff.deleted_files.append(target_conflict_file)
target_files.pop(name, None)
@@ -891,7 +897,7 @@ class SemanticProcessor(DequeueHandlerBase):
target_subdir,
recursive=True,
ctx=ctx,
- lease_ref=lock,
+ lock_handle=lock_handle,
)
diff.deleted_dirs.append(target_subdir)
except Exception as e:
@@ -908,7 +914,7 @@ class SemanticProcessor(DequeueHandlerBase):
root_subdir,
target_subdir_uri,
ctx=ctx,
- lease_ref=lock,
+ lock_handle=lock_handle,
)
except Exception as e:
logger.error(
@@ -923,14 +929,9 @@ 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,
- lease_ref=lock,
- )
+ await viking_fs.mkdir(parent_uri.uri, exist_ok=True, ctx=ctx)
diff.added_dirs.append(target_uri)
- await viking_fs.mv(root_uri, target_uri, ctx=ctx, lease_ref=lock)
+ await viking_fs.mv(root_uri, target_uri, ctx=ctx, lock_handle=lock_handle)
# 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)
@@ -952,7 +953,7 @@ class SemanticProcessor(DequeueHandlerBase):
root_uri: str,
target_uri: str,
ctx: Optional[RequestContext] = None,
- lock: Optional[Dict[str, Any]] = None,
+ lock: LockLease = NO_LOCK,
) -> None:
"""Rewrite local image refs in the target after a temp-to-target sync.
@@ -1015,14 +1016,14 @@ class SemanticProcessor(DequeueHandlerBase):
target_mapping,
mapping_content,
ctx=ctx,
- lease_ref=lock,
+ lock_handle=lock.handle,
)
except Exception:
# Target subtree may not exist (doc removed in sync); skip.
pass
try:
- await rewrite_image_uris(target_uri, ctx=ctx, lease_ref=lock)
+ await rewrite_image_uris(target_uri, ctx=ctx, lock_handle=lock.handle)
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 093001491..0c5c083fd 100644
--- a/openviking/storage/queuefs/semantic_sidecar.py
+++ b/openviking/storage/queuefs/semantic_sidecar.py
@@ -2,9 +2,10 @@
# SPDX-License-Identifier: AGPL-3.0
"""Shared writeback for semantic sidecar files."""
-from typing import Any, Callable, Dict, Optional
+from typing import Any, Callable, 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__)
@@ -18,31 +19,34 @@ async def write_semantic_sidecars(
abstract: str,
ctx: Optional[RequestContext],
is_stale: Callable[[], bool],
- lock: Optional[Dict[str, Any]] = None,
+ lock: LockLease = NO_LOCK,
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),
]
- 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:
+ async with LockContext(lock_manager, lock_paths, lock_mode="exact", handle=lock.handle):
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, sidecar_lease)
+ await _write_sidecars(viking_fs, dir_uri, overview, abstract, ctx, lock.handle)
return True
- finally:
- if owns_lease:
- await viking_fs._async_agfs.pathlock_release(sidecar_lease)
async def _write_sidecars(
@@ -51,18 +55,18 @@ async def _write_sidecars(
overview: str,
abstract: str,
ctx: Optional[RequestContext],
- lease_ref: Optional[Dict[str, Any]] = None,
+ lock_handle: Any = None,
) -> None:
- """Write sidecar files to the target directory."""
+ # TODO: This must be optimized once pathlock is pushed down into ragfs.
await viking_fs.write_file(
f"{dir_uri}/.overview.md",
overview,
ctx=ctx,
- lease_ref=lease_ref,
+ lock_handle=lock_handle,
)
await viking_fs.write_file(
f"{dir_uri}/.abstract.md",
abstract,
ctx=ctx,
- lease_ref=lease_ref,
+ lock_handle=lock_handle,
)
diff --git a/openviking/storage/transaction/__init__.py b/openviking/storage/transaction/__init__.py
index 93e772ac0..cdcd30756 100644
--- a/openviking/storage/transaction/__init__.py
+++ b/openviking/storage/transaction/__init__.py
@@ -3,12 +3,46 @@
"""
Transaction module for OpenViking.
-Path-lock management has been moved to the Rust ragfs layer.
-Python-side lock operations now go through RAGFSBindingClient.pathlock_* methods.
+Provides path-lock management and redo-log crash recovery.
"""
+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
new file mode 100644
index 000000000..424cca343
--- /dev/null
+++ b/openviking/storage/transaction/lock_context.py
@@ -0,0 +1,97 @@
+# 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
new file mode 100644
index 000000000..0e2c8f084
--- /dev/null
+++ b/openviking/storage/transaction/lock_handle.py
@@ -0,0 +1,48 @@
+# 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
new file mode 100644
index 000000000..3cbf26ddb
--- /dev/null
+++ b/openviking/storage/transaction/lock_lease.py
@@ -0,0 +1,229 @@
+# 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
new file mode 100644
index 000000000..d31efc612
--- /dev/null
+++ b/openviking/storage/transaction/lock_manager.py
@@ -0,0 +1,594 @@
+# 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
new file mode 100644
index 000000000..7b80c8dfb
--- /dev/null
+++ b/openviking/storage/transaction/path_lock.py
@@ -0,0 +1,859 @@
+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 bf4bdc669..e9ebfdaf7 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, Dict, List, Optional, TypeVar, Union
+from typing import TYPE_CHECKING, Any, Awaitable, Callable, Dict, List, Optional, TypeVar, Union
from openviking.core.context import ContextLevel
from openviking.core.namespace import (
@@ -49,7 +49,10 @@ 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 STORAGE_INTERNAL_ENTRY_NAMES
+from openviking.storage.internal_names import (
+ MULTIWRITE_PATH_LOCK_FILE,
+ 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
@@ -66,6 +69,7 @@ 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
@@ -419,6 +423,38 @@ 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)
@@ -559,39 +595,20 @@ 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, lease_ref=lease_ref)
+ await self._ensure_parent_dirs(path, ctx=ctx)
try:
- await self._async_agfs.mkdir(path, fs_ctx=self._pathlock_fs_ctx(ctx, lease_ref))
+ await self._async_agfs.mkdir(path)
except Exception as exc:
message = str(exc).lower()
already_exists = "exist" in message or "already" in message
@@ -603,7 +620,7 @@ class VikingFS:
uri: str,
recursive: bool = False,
ctx: Optional[RequestContext] = None,
- lease_ref: Dict[str, Any] | None = None,
+ lock_handle: Optional["LockHandle"] = None,
) -> Dict[str, Any]:
"""Delete file/directory + recursively update vector index.
@@ -619,6 +636,7 @@ 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)
@@ -664,62 +682,61 @@ class VikingFS:
f"Cannot remove directory without --recursive: {uri}",
details={"resource": uri, "expected_flag": "recursive"},
)
- lock_method = self._async_agfs.pathlock_acquire_tree
+ lock_paths = [path]
+ lock_mode = "tree"
else:
- 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)
+ lock_paths = [path]
+ lock_mode = "exact"
try:
- 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),
- )
- except AGFSDirectoryNotEmptyError:
- raise FailedPreconditionError(
- f"Directory not empty: {uri}. Use recursive=True to delete non-empty directories."
+ 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 []
)
- except RuntimeError as e:
- # Fallback for older versions without typed exceptions
- if _is_directory_not_empty_error(str(e)):
+ 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:
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
- finally:
- if lease_ref is None:
- await self._async_agfs.pathlock_release(lease)
+ 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)
async def mv(
self,
old_uri: str,
new_uri: str,
ctx: Optional[RequestContext] = None,
- lease_ref: Dict[str, Any] | None = None,
+ lock_handle: Optional["LockHandle"] = None,
) -> Dict[str, Any]:
- """Move file/directory while extending an optional outer pathlock lease.
+ """Move file/directory + recursively update vector index.
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
@@ -770,24 +787,25 @@ class VikingFS:
old_uri = canonicalize_uri(old_uri, real_ctx)
new_uri = canonicalize_uri(new_uri, real_ctx)
- 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,
+ lock_context = (
+ LockContext(
+ get_lock_manager(),
+ [old_path],
+ lock_mode="mv",
+ mv_dst_path=new_path,
+ src_is_dir=True,
+ 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,
+ if is_dir
+ else LockContext(
+ get_lock_manager(),
+ [old_path, new_path],
+ lock_mode="exact",
+ handle=lock_handle,
)
+ )
- try:
+ async with lock_context as active_lock_handle:
uris_to_move = (
await self._collect_uris(old_path, recursive=True, ctx=ctx) if is_dir else []
)
@@ -806,7 +824,7 @@ class VikingFS:
is_dir=is_dir,
is_temp=is_temp,
ctx=ctx,
- lease_ref=lease,
+ lock_handle=active_lock_handle,
)
except Exception as e:
if "not found" in str(e).lower():
@@ -821,42 +839,30 @@ 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:
- 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)
+ await self._async_agfs.rm(new_path, recursive=True)
else:
- await self._async_agfs.rm(
- new_path,
- fs_ctx=self._pathlock_fs_ctx(ctx, lease),
- )
+ await self._async_agfs.rm(new_path)
except Exception:
pass
raise
# Delete source
- await self._async_agfs.rm(
- old_path,
- recursive=is_dir,
- fs_ctx=self._pathlock_fs_ctx(ctx, lease),
- )
+ await self._async_agfs.rm(old_path, recursive=is_dir)
return {}
- finally:
- await self._async_agfs.pathlock_release(lease)
async def system_sync_status(
self, uri: str, ctx: Optional[RequestContext] = None
@@ -891,91 +897,39 @@ class VikingFS:
is_dir: bool,
is_temp: bool,
ctx: Optional[RequestContext] = None,
- lease_ref: Dict[str, Any] | None = None,
+ lock_handle: Optional["LockHandle"] = None,
) -> None:
"""Copy source to destination for mv without deleting source."""
if is_temp:
- 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),
- )
+ await self._async_agfs.cp(
+ old_path,
+ new_path,
+ recursive=is_dir,
+ fs_ctx={"account_id": self._ctx_or_default(ctx).account_id},
+ )
return
if is_dir:
- await self._copy_dir_through_vikingfs(old_uri, new_uri, ctx=ctx, lease_ref=lease_ref)
+ await self._copy_dir_through_vikingfs(
+ old_uri, new_uri, ctx=ctx, lock_handle=lock_handle
+ )
else:
- 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,
+ await self._copy_file_through_vikingfs(
+ old_uri,
+ new_uri,
+ ctx=ctx,
+ lock_handle=lock_handle,
)
- 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,
- lease_ref: Dict[str, Any] | None = None,
+ lock_handle: Optional["LockHandle"] = None,
) -> None:
"""Recursively copy a directory through VikingFS read/write hooks."""
- await self.mkdir(new_uri, exist_ok=True, ctx=ctx, lease_ref=lease_ref)
+ await self.mkdir(new_uri, exist_ok=True, ctx=ctx)
entries = await self.ls(old_uri, show_all_hidden=True, ctx=ctx)
for entry in entries:
@@ -989,14 +943,14 @@ class VikingFS:
old_child_uri,
new_child_uri,
ctx=ctx,
- lease_ref=lease_ref,
+ lock_handle=lock_handle,
)
else:
await self._copy_file_through_vikingfs(
old_child_uri,
new_child_uri,
ctx=ctx,
- lease_ref=lease_ref,
+ lock_handle=lock_handle,
)
async def _copy_file_through_vikingfs(
@@ -1004,23 +958,11 @@ class VikingFS:
from_uri: str,
to_uri: str,
ctx: Optional[RequestContext] = None,
- lease_ref: Dict[str, Any] | None = None,
+ lock_handle: Optional["LockHandle"] = None,
) -> None:
"""Copy one file through VikingFS read/write hooks without deleting source."""
content_bytes = await self.read_file_bytes(from_uri, ctx=ctx)
- 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)
+ await self.write_file_bytes(to_uri, content_bytes, ctx=ctx, lock_handle=lock_handle)
async def grep(
self,
@@ -1236,15 +1178,19 @@ 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,
@@ -1414,11 +1360,13 @@ 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
@@ -1588,11 +1536,13 @@ 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}")
@@ -1615,7 +1565,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 pathlock system is not enabled or the lookup
+ False when the LockManager is not initialized or the lookup
fails.
count (int): For directories, the number of nodes in the vector index
under this directory (including subdirectories). For files, this
@@ -1678,9 +1628,11 @@ class VikingFS:
return result
async def _is_path_locked_async(self, path: str) -> bool:
- """Best-effort async path-lock lookup; returns False on any error."""
+ """Best-effort async path-lock lookup; returns False when LockManager is absent."""
try:
- return await self._async_agfs.pathlock_is_locked(path)
+ from openviking.storage.transaction import get_lock_manager
+
+ return await get_lock_manager().is_path_locked_async(path)
except Exception:
return False
@@ -1875,15 +1827,17 @@ 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
@@ -1908,13 +1862,15 @@ 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)
@@ -3093,28 +3049,17 @@ class VikingFS:
# ========== Parent Directory Creation ==========
- async def _ensure_parent_dirs(
- self,
- path: str,
- ctx: Optional[RequestContext] = None,
- lease_ref: Dict[str, Any] | None = None,
- ) -> None:
+ async def _ensure_parent_dirs(self, path: str, ctx: Optional[RequestContext] = None) -> None:
"""Recursively create all parent directories."""
try:
- await self._async_agfs.ensure_parent_dirs(
- path,
- fs_ctx=self._pathlock_fs_ctx(ctx, lease_ref),
- )
+ await self._async_agfs.ensure_parent_dirs(path)
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, lease_ref=lease_ref)
+ await self._mkdir_path_with_parents(parent, ctx=ctx)
async def _mkdir_path_with_parents(
- self,
- dir_path: str,
- ctx: Optional[RequestContext] = None,
- lease_ref: Dict[str, Any] | None = None,
+ self, dir_path: str, ctx: Optional[RequestContext] = 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]
@@ -3122,10 +3067,7 @@ class VikingFS:
for part in parts:
current = f"{current}/{part}"
try:
- await self._async_agfs.mkdir(
- current,
- fs_ctx=self._pathlock_fs_ctx(ctx, lease_ref),
- )
+ await self._async_agfs.mkdir(current)
except Exception as e:
message = str(e).lower()
if "exist" in message or "already" in message:
@@ -3202,17 +3144,21 @@ class VikingFS:
uri: str,
content: Union[str, bytes],
ctx: Optional[RequestContext] = None,
- lease_ref: Dict[str, Any] | None = None,
+ lock_handle: Optional["LockHandle"] = None,
) -> None:
- """Write file directly. Encryption lock handled internally by EncryptionWrappedFS."""
+ """Write file directly."""
self._ensure_mutable_access(uri, ctx)
path = self._uri_to_path(uri, ctx=ctx)
- await self._ensure_parent_dirs(path, ctx=ctx, lease_ref=lease_ref)
+ await self._ensure_parent_dirs(path, ctx=ctx)
if isinstance(content, str):
content = content.encode("utf-8")
- await self._async_agfs.write(path, content, fs_ctx=self._pathlock_fs_ctx(ctx, lease_ref))
+ await self._run_with_encrypted_write_lock(
+ path,
+ lambda: self._async_agfs.write(path, content),
+ lock_handle=lock_handle,
+ )
async def read_file(
self,
@@ -3313,63 +3259,59 @@ class VikingFS:
uri: str,
content: bytes,
ctx: Optional[RequestContext] = None,
- lease_ref: Dict[str, Any] | None = None,
+ lock_handle: Optional["LockHandle"] = None,
) -> None:
- """Write single binary file. Encryption lock handled internally by EncryptionWrappedFS."""
+ """Write single binary file."""
self._ensure_mutable_access(uri, ctx)
path = self._uri_to_path(uri, ctx=ctx)
- await self._ensure_parent_dirs(path, ctx=ctx, lease_ref=lease_ref)
+ await self._ensure_parent_dirs(path, ctx=ctx)
- await self._async_agfs.write(path, content, fs_ctx=self._pathlock_fs_ctx(ctx, lease_ref))
+ await self._run_with_encrypted_write_lock(
+ path,
+ lambda: self._async_agfs.write(path, content),
+ lock_handle=lock_handle,
+ )
async def append_file(
self,
uri: str,
content: str,
ctx: Optional[RequestContext] = None,
- lease_ref: Dict[str, Any] | None = None,
+ lock_handle: Optional["LockHandle"] = None,
) -> None:
- """Append content to file while holding one exact pathlock lease."""
+ """Append content to file."""
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, 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:
+ 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:
raise
- except AGFSClientError:
- raise
- final_content = (existing + content).encode("utf-8")
- await self._async_agfs.write(
+ final_content = (existing + content).encode("utf-8")
+ await self._async_agfs.write(path, final_content)
+
+ await self._run_with_encrypted_write_lock(
path,
- final_content,
- fs_ctx=fs_ctx,
+ _append_under_lock,
+ lock_handle=lock_handle,
)
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,
@@ -3602,32 +3544,24 @@ 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)
- fs_ctx = self._pathlock_fs_ctx(ctx, lease_ref)
- await self._ensure_parent_dirs(dst_path, ctx=ctx, lease_ref=lease_ref)
+ await self._ensure_parent_dirs(dst_path, ctx=ctx)
await self._async_agfs.cp(
src_path,
dst_path,
recursive=True,
- fs_ctx=fs_ctx or {"account_id": self._ctx_or_default(ctx).account_id},
+ fs_ctx={"account_id": self._ctx_or_default(ctx).account_id},
)
- async def delete_temp(
- self,
- temp_uri: str,
- ctx: Optional[RequestContext] = None,
- lease_ref: Dict[str, Any] | None = None,
- ) -> None:
+ async def delete_temp(self, temp_uri: str, ctx: Optional[RequestContext] = 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", "")
@@ -3635,10 +3569,10 @@ class VikingFS:
continue
entry_path = f"{path}/{name}"
if entry.get("isDir"):
- await self.delete_temp(f"{temp_uri}/{name}", ctx=ctx, lease_ref=lease_ref)
+ await self.delete_temp(f"{temp_uri}/{name}", ctx=ctx)
else:
- await self._async_agfs.rm(entry_path, fs_ctx=fs_ctx)
- await self._async_agfs.rm(path, fs_ctx=fs_ctx)
+ await self._async_agfs.rm(entry_path)
+ await self._async_agfs.rm(path)
except Exception as e:
logger.warning(f"[VikingFS] Failed to delete temp {temp_uri}: {e}")
@@ -3731,14 +3665,16 @@ 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]"
@@ -4015,6 +3951,7 @@ 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
@@ -4029,25 +3966,21 @@ class VikingFS:
)
partial_exc: Optional[GitRestoreWritebackPartialError] = None
try:
- lease = await self._async_agfs.pathlock_acquire_tree(lock_path)
+ 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
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
@@ -4406,10 +4339,12 @@ 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 7e36d243c..0495f8961 100644
--- a/openviking/utils/agfs_utils.py
+++ b/openviking/utils/agfs_utils.py
@@ -35,7 +35,6 @@ 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 bae96a1b8..5ded05951 100644
--- a/openviking/utils/resource_processor.py
+++ b/openviking/utils/resource_processor.py
@@ -27,6 +27,12 @@ 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
@@ -171,7 +177,7 @@ class ResourceProcessor:
"source_path": None,
}
defer_post_processing = bool(kwargs.pop("defer_post_processing", False))
- preacquired_lock = kwargs.pop("resource_lock", None)
+ preacquired_lock = kwargs.pop("resource_lock", NO_LOCK) or NO_LOCK
telemetry = get_current_telemetry()
async def _set_stage(stage: str) -> None:
@@ -313,17 +319,20 @@ 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: Optional[Dict[str, Any]] = preacquired_lock
+ resource_lock: LockLease = 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 is not None:
+ if resource_lock.active:
root_uri = candidate_uri
else:
root_uri, resource_lock = await self.reserve_unique_candidate(
@@ -358,21 +367,17 @@ class ResourceProcessor:
target_preexisting = False
except Exception:
pass
- if resource_lock is None:
+ if not resource_lock.active:
dst_path = viking_fs._uri_to_path(root_uri, ctx=ctx)
- resource_lock = await self.acquire_resource_lock(dst_path, uri=root_uri)
+ resource_lock = await self.acquire_resource_lock(
+ lock_manager, dst_path, uri=root_uri
+ )
if not target_preexisting:
- 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.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.delete_temp(parse_result.temp_dir_path, ctx=ctx)
temp_uri = root_uri
source_committed = True
except Exception:
@@ -431,7 +436,7 @@ class ResourceProcessor:
prepared: Dict[str, Any],
*,
ctx: RequestContext,
- resource_lock: Optional[Dict[str, Any]] = None,
+ resource_lock: LockLease = NO_LOCK,
summarize: bool = False,
processing_mode: ProcessingMode = DEFAULT_PROCESSING_MODE,
**kwargs: Any,
@@ -466,12 +471,12 @@ class ResourceProcessor:
**kwargs,
)
if (
- resource_lock is not None
+ resource_lock.active
and summary_result.get("status") == "success"
and summary_result.get("enqueued_count", 0) > 0
):
- await get_viking_fs()._async_agfs.pathlock_handoff(resource_lock)
- resource_lock = None
+ await resource_lock.handoff()
+ resource_lock = NO_LOCK
except Exception as exc:
logger.error("Summarization failed: %s", exc)
result["warnings"] = [f"Summarization failed: {exc}"]
@@ -487,7 +492,7 @@ class ResourceProcessor:
except Exception:
pass
- if resource_lock is not None:
+ if resource_lock.active:
try:
sync_deleted_files: list[str] = []
sync_deleted_dirs: list[str] = []
@@ -503,16 +508,11 @@ 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,
- lease_ref=resource_lock,
- )
+ await viking_fs.persist_temp_tree(temp_uri, root_uri, ctx=ctx)
await rewrite_image_uris(
root_uri,
ctx=ctx,
- lease_ref=resource_lock,
+ lock_handle=resource_lock.handle,
)
if temp_dir_path:
await viking_fs.delete_temp(temp_dir_path, ctx=ctx)
@@ -526,7 +526,7 @@ class ResourceProcessor:
if vectors_only and build_index:
await self._vectorize_resource_files(root_uri, ctx=ctx)
finally:
- await get_viking_fs()._async_agfs.pathlock_release(resource_lock)
+ await resource_lock.close()
elif vectors_only:
if not build_index:
return result
@@ -552,11 +552,13 @@ 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,
@@ -598,11 +600,13 @@ class ResourceProcessor:
candidate_uri: str,
ctx: RequestContext,
max_attempts: int = 100,
- ) -> tuple[str, Dict[str, Any]]:
+ ) -> tuple[str, OwnedLockLease]:
"""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):
@@ -613,7 +617,7 @@ class ResourceProcessor:
dst_path = viking_fs._uri_to_path(root_uri, ctx=ctx)
try:
resource_lock = await self.acquire_resource_lock(
- dst_path, uri=root_uri, timeout=0.0
+ lock_manager, dst_path, uri=root_uri, timeout=0.0
)
return root_uri, resource_lock
except ResourceBusyError as exc:
@@ -635,18 +639,17 @@ class ResourceProcessor:
@staticmethod
async def acquire_resource_lock(
+ lock_manager,
path: str,
*,
uri: str = "",
- timeout: float = 0.0,
- ) -> Dict[str, Any]:
+ timeout: Any = LOCK_TIMEOUT_DEFAULT,
+ ) -> OwnedLockLease:
"""Acquire the per-resource TreeLock or raise a structured conflict."""
from openviking.storage.errors import ResourceBusyError
try:
- return await get_viking_fs()._async_agfs.pathlock_acquire_tree(
- path, timeout_secs=timeout
- )
+ return await OwnedLockLease.acquire_tree(lock_manager, path, timeout=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 88560efd3..50afe9e77 100644
--- a/openviking/utils/summarizer.py
+++ b/openviking/utils/summarizer.py
@@ -9,6 +9,7 @@ from typing import TYPE_CHECKING, Any, Dict, List, Optional, Tuple
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
@@ -35,7 +36,7 @@ class Summarizer:
resource_uris: List[str],
ctx: "RequestContext",
skip_vectorization: bool = False,
- lock: Optional[Dict[str, Any]] = None,
+ lock: LockLease = NO_LOCK,
**kwargs,
) -> Dict[str, Any]:
"""
@@ -59,9 +60,7 @@ class Summarizer:
enqueued_count = 0
telemetry = get_current_telemetry()
- lock_handoff: Optional[Dict[str, Any]] = None
- if lock is not None:
- lock_handoff = await get_viking_fs()._async_agfs.pathlock_to_handoff(lock)
+ lock_handoff = lock.to_handoff()
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 feed25756..3f6a5b190 100644
--- a/openviking_cli/utils/config/agfs_config.py
+++ b/openviking_cli/utils/config/agfs_config.py
@@ -315,30 +315,6 @@ 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)."""
@@ -405,11 +381,6 @@ 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 b5aa084e4..efcce6889 100644
--- a/tests/agfs/test_async_client.py
+++ b/tests/agfs/test_async_client.py
@@ -8,24 +8,15 @@ 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 ef074e043..0f6c913c3 100644
--- a/tests/agfs/test_fs_binding.py
+++ b/tests/agfs/test_fs_binding.py
@@ -13,6 +13,7 @@ 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
@@ -32,12 +33,16 @@ 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:
@@ -91,78 +96,6 @@ 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 af545efdf..0e0020bc0 100644
--- a/tests/agfs/test_fs_binding_s3.py
+++ b/tests/agfs/test_fs_binding_s3.py
@@ -13,6 +13,7 @@ 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
@@ -58,10 +59,14 @@ 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 f1b489d92..c7609c00b 100644
--- a/tests/agfs/test_viking_fs_git.py
+++ b/tests/agfs/test_viking_fs_git.py
@@ -80,16 +80,21 @@ 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:
- pass
+ reset_lock_manager()
@pytest.fixture
def vfs_disabled(workspace):
+ from openviking.storage.transaction import init_lock_manager, reset_lock_manager
+
cfg = workspace / "ragfs.toml"
cfg.write_text(
"""
@@ -101,10 +106,11 @@ 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:
- pass
+ reset_lock_manager()
# =========================================================================
@@ -453,12 +459,15 @@ 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:
- pass
+ reset_lock_manager()
@pytest.mark.asyncio
diff --git a/tests/client/test_file_operations.py b/tests/client/test_file_operations.py
index 6d2edb64c..2df2a910c 100644
--- a/tests/client/test_file_operations.py
+++ b/tests/client/test_file_operations.py
@@ -8,6 +8,7 @@ from pathlib import Path
import pytest
from openviking import AsyncOpenViking
+from openviking.storage.transaction import release_all_locks
class TestRm:
@@ -22,6 +23,7 @@ class TestRm:
reason="Test rm",
)
+ await release_all_locks()
uris = await client.tree(result["root_uri"])
for data in uris:
if not data["isDir"]:
@@ -35,6 +37,8 @@ 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"]:
@@ -56,6 +60,7 @@ 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 4a8ba850e..4fc8e43c3 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,8 +86,11 @@ 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()
@@ -128,20 +131,24 @@ 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:
- pass
+ reset_lock_manager()
@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:
- pass
+ reset_lock_manager()
async def test_write_commit_show_roundtrip(git_harness):
@@ -158,13 +165,10 @@ 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):
@@ -280,13 +284,10 @@ 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"]]
@@ -319,13 +320,10 @@ 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)
@@ -400,13 +398,19 @@ 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 fbc4bf30e..3323645f7 100644
--- a/tests/client/test_git_versioning_http.py
+++ b/tests/client/test_git_versioning_http.py
@@ -24,18 +24,19 @@ 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
@@ -85,6 +86,7 @@ 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)
@@ -105,6 +107,7 @@ async def http_service(http_temp_dir: Path, monkeypatch):
yield svc
finally:
await svc.close()
+ reset_lock_manager()
@pytest_asyncio.fixture(scope="function")
@@ -192,7 +195,6 @@ 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 5fd735617..ff8263f5f 100644
--- a/tests/client/test_import_export.py
+++ b/tests/client/test_import_export.py
@@ -12,6 +12,7 @@ from pathlib import Path
import pytest
from openviking import AsyncOpenViking
+from openviking.storage.transaction import release_all_locks
class TestExportOvpack:
@@ -99,6 +100,7 @@ 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 285addf23..b14bd417b 100644
--- a/tests/integration/test_full_workflow.py
+++ b/tests/integration/test_full_workflow.py
@@ -10,6 +10,7 @@ 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")
@@ -175,6 +176,7 @@ 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 9f8491245..539a97499 100644
--- a/tests/metrics/collectors/test_state_collectors.py
+++ b/tests/metrics/collectors/test_state_collectors.py
@@ -3,12 +3,16 @@
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,
)
@@ -229,6 +233,31 @@ 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 dccbfcffa..6b819798c 100644
--- a/tests/misc/test_config_validation.py
+++ b/tests/misc/test_config_validation.py
@@ -584,30 +584,9 @@ 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 922e59068..90de9062d 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.run_async")
- @patch("openviking.service.debug_service.get_viking_fs")
+ @patch("openviking.service.debug_service.get_lock_manager")
@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_viking_fs,
- mock_run_async,
+ mock_get_lock_mgr,
):
"""Test system property when all components are healthy."""
# Setup mocks
@@ -225,6 +225,7 @@ class TestObserverService:
mock_queue_cls,
mock_vikingdb_cls,
mock_models_cls,
+ mock_lock_cls,
mock_retrieval_cls,
]:
mock_observer = MagicMock()
@@ -233,15 +234,8 @@ class TestObserverService:
mock_observer.get_status_table.return_value = "OK"
mock_cls.return_value = mock_observer
- # 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 get_lock_manager to return a MagicMock
+ mock_get_lock_mgr.return_value = MagicMock()
mock_config = MagicMock(spec=["vlm"]) # Only allow vlm attribute
mock_config.vlm.get_vlm_instance.return_value = MagicMock()
@@ -254,9 +248,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.run_async")
- @patch("openviking.service.debug_service.get_viking_fs")
+ @patch("openviking.service.debug_service.get_lock_manager")
@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")
@@ -267,9 +261,9 @@ class TestObserverService:
mock_queue_cls,
mock_vikingdb_cls,
mock_models_cls,
+ mock_lock_cls,
mock_retrieval_cls,
- mock_get_viking_fs,
- mock_run_async,
+ mock_get_lock_mgr,
):
"""Test system property when some components have errors."""
# Queue has errors
@@ -293,22 +287,16 @@ class TestObserverService:
mock_models.get_status_table.return_value = "Error"
mock_models_cls.return_value = mock_models
- # 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": [],
- }
+ # 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()
mock_config = MagicMock(spec=["vlm"]) # Only allow vlm attribute
mock_config.vlm.get_vlm_instance.return_value = MagicMock()
@@ -322,8 +310,7 @@ class TestObserverService:
assert "queue has errors" in non_transaction_errors
assert "models has errors" in non_transaction_errors
- @patch("openviking.service.debug_service.run_async")
- @patch("openviking.service.debug_service.get_viking_fs")
+ @patch("openviking.service.debug_service.get_lock_manager")
@patch("openviking.service.debug_service.get_queue_manager")
@patch("openviking.service.debug_service.QueueObserver")
@patch("openviking.service.debug_service.VikingDBObserver")
@@ -334,8 +321,7 @@ class TestObserverService:
mock_vikingdb_cls,
mock_queue_cls,
mock_get_queue_mgr,
- mock_get_viking_fs,
- mock_run_async,
+ mock_get_lock_mgr,
):
"""Test is_healthy returns True when system is healthy."""
for mock_cls in [mock_queue_cls, mock_vikingdb_cls, mock_models_cls]:
@@ -345,14 +331,7 @@ class TestObserverService:
mock_observer.get_status_table.return_value = "OK"
mock_cls.return_value = mock_observer
- 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_get_lock_mgr.return_value = MagicMock()
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 9090efbd0..b364be0bc 100644
--- a/tests/misc/test_resource_processor_mv.py
+++ b/tests/misc/test_resource_processor_mv.py
@@ -39,36 +39,59 @@ class _CtxMgr:
return False
-class _FakePathLock:
+class _FakeLockManager:
def __init__(self, *, busy_tree_paths=None):
- self._next_id = 0
- self.acquired_tree_paths: list[str] = []
- self.tree_attempts: list[tuple[str, float]] = []
+ 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.busy_tree_paths = set(busy_tree_paths or [])
- def _new_lease(self):
- self._next_id += 1
- return {"id": f"lock-{self._next_id}"}
+ def create_handle(self):
+ handle = self._lock_handle_cls()
+ self._handles[handle.id] = handle
+ return handle
- async def pathlock_acquire_tree(self, path, timeout_secs=0.0):
- from openviking.storage.errors import LockAcquisitionError
+ 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
- self.tree_attempts.append((path, timeout_secs))
+ async def acquire_tree(self, handle, path, timeout=None):
+ self.tree_attempts.append((path, timeout))
if path in self.busy_tree_paths:
- raise LockAcquisitionError(f"busy: {path}")
+ return False
+ lock_path = f"tree:{path}"
+ handle.add_lock(lock_path)
self.acquired_tree_paths.append(path)
- return self._new_lease()
+ return True
- async def pathlock_release(self, lease):
- pass
+ 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
class _FakeVikingFS:
- def __init__(self, *, exists_result=False, existing_uris=None, pathlock=None):
+ def __init__(self, *, exists_result=False, existing_uris=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 = []
@@ -87,12 +110,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, lease_ref=None):
- self.delete_temp_calls.append((temp_dir_path, lease_ref))
+ async def delete_temp(self, temp_dir_path, ctx=None):
+ self.delete_temp_calls.append(temp_dir_path)
return None
- 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))
+ async def persist_temp_tree(self, temp_uri, target_uri, ctx=None):
+ self.persist_calls.append((temp_uri, target_uri))
self.agfs.write(self._uri_to_path(target_uri, ctx=ctx), b"content")
async def glob(self, pattern, uri=None, ctx=None):
@@ -112,6 +135,7 @@ 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(
@@ -119,6 +143,10 @@ 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()
@@ -148,10 +176,8 @@ 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", {"id": "lock-1"})
- ]
- assert fake_fs.delete_temp_calls == [("viking://temp/tmpdir", None)]
+ assert fake_fs.persist_calls == [("viking://temp/root_tmp", "viking://resources/root")]
+ assert fake_fs.delete_temp_calls == ["viking://temp/tmpdir"]
assert summarize_calls[0]["temp_uris"] == ["viking://resources/root"]
assert summarize_calls[0]["target_preexisting"] is False
@@ -161,6 +187,7 @@ 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(
@@ -168,6 +195,10 @@ 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()
@@ -206,8 +237,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_pathlock = _FakePathLock(busy_tree_paths={"/mock/resources/root_1"})
- fake_fs = _FakeVikingFS(existing_uris={"viking://resources/root"}, pathlock=fake_pathlock)
+ fake_fs = _FakeVikingFS(existing_uris={"viking://resources/root"})
+ fake_lock_manager = _FakeLockManager(busy_tree_paths={"/mock/resources/root_1"})
summarize_calls = []
monkeypatch.setattr(
@@ -215,6 +246,10 @@ 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()
@@ -250,13 +285,12 @@ async def test_resource_processor_auto_candidate_skips_existing_and_busy(monkeyp
"viking://resources/root_1",
"viking://resources/root_2",
]
- assert fake_pathlock.tree_attempts == [
+ assert fake_lock_manager.tree_attempts == [
("/mock/resources/root_1", 0.0),
("/mock/resources/root_2", 0.0),
]
- assert fake_pathlock.acquired_tree_paths == ["/mock/resources/root_2"]
+ assert fake_lock_manager.acquired_exact_paths == []
+ assert fake_lock_manager.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", {"id": "lock-1"})
- ]
+ assert fake_fs.persist_calls == [("viking://temp/root_tmp", "viking://resources/root_2")]
diff --git a/tests/parse/test_feishu_parser_api.py b/tests/parse/test_feishu_parser_api.py
index abced3470..4dbbded75 100644
--- a/tests/parse/test_feishu_parser_api.py
+++ b/tests/parse/test_feishu_parser_api.py
@@ -440,6 +440,10 @@ 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(),
@@ -505,12 +509,7 @@ 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 = {"lease_ref": "lock-1"}
- agfs = SimpleNamespace(
- pathlock_to_handoff=AsyncMock(return_value={"handle_id": "lock-1"}),
- pathlock_handoff=AsyncMock(),
- pathlock_release=AsyncMock(),
- )
+ resource_lock = SimpleNamespace(to_handoff=Mock(return_value=None))
resource_processor = SimpleNamespace(
process_resource=AsyncMock(
return_value={
@@ -523,7 +522,7 @@ async def test_local_prepared_job_uses_add_resource_queue(monkeypatch):
)
service = ResourceService(
- viking_fs=SimpleNamespace(_async_agfs=agfs),
+ viking_fs=SimpleNamespace(),
resource_processor=resource_processor,
skill_processor=SimpleNamespace(),
)
@@ -549,8 +548,6 @@ 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
@@ -564,7 +561,6 @@ 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":
@@ -583,17 +579,19 @@ async def test_uat_producer_cancellation_respects_queue_ownership(
fail=AsyncMock(),
)
queue_manager = SimpleNamespace(enqueue=enqueue)
- 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"],
- }
+ lock_lease = SimpleNamespace(
+ to_handoff=Mock(
+ return_value=SimpleNamespace(
+ to_dict=Mock(
+ return_value={
+ "handle_id": "lock-1",
+ "lock_paths": ["/resources/fixed"],
+ }
+ )
+ )
),
- pathlock_handoff=handoff,
- pathlock_release=release,
+ handoff=handoff,
+ close=AsyncMock(),
)
monkeypatch.setattr(
"openviking.service.task_tracker.get_task_tracker",
@@ -603,12 +601,17 @@ 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",
- _async_agfs=agfs,
- ),
+ viking_fs=SimpleNamespace(_uri_to_path=lambda _uri, ctx: "/resources/fixed"),
resource_processor=resource_processor,
skill_processor=SimpleNamespace(),
)
@@ -632,7 +635,7 @@ async def test_uat_producer_cancellation_respects_queue_ownership(
args={"feishu_access_token": "u-secret"},
)
- release.assert_awaited_once_with(lock_lease)
+ lock_lease.close.assert_awaited_once_with()
task_tracker.create.assert_not_awaited()
task_tracker.fail.assert_not_awaited()
if cancel_stage == "submit":
@@ -798,7 +801,6 @@ 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 a1f26f494..2f99ba884 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, lease_ref=None)
+ stats = await rewrite_image_uris(root, lock_handle=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, lease_ref=None)
+ stats = await rewrite_image_uris(root, lock_handle=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, lease_ref=None)
+ stats = await rewrite_image_uris(root, lock_handle=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, lease_ref=None)
+ stats = await rewrite_image_uris(root, lock_handle=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, lease_ref=None)
+ stats = await rewrite_image_uris(root, lock_handle=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 5e85ed22a..0904c3638 100644
--- a/tests/server/conftest.py
+++ b/tests/server/conftest.py
@@ -24,6 +24,7 @@ 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
@@ -167,6 +168,7 @@ 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(
@@ -177,6 +179,7 @@ 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")
@@ -230,6 +233,7 @@ 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 b9e8c7100..7f7695d49 100644
--- a/tests/server/test_admin_api.py
+++ b/tests/server/test_admin_api.py
@@ -43,6 +43,19 @@ 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 = {}
@@ -135,6 +148,12 @@ 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 c25177145..309c02efe 100644
--- a/tests/server/test_api_key_manager.py
+++ b/tests/server/test_api_key_manager.py
@@ -15,6 +15,7 @@ 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,
@@ -170,54 +171,32 @@ 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 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)
+ 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)
- 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"
- 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)
+ 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)
- 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 225023b0c..8841d9f57 100644
--- a/tests/server/test_content_batch_write.py
+++ b/tests/server/test_content_batch_write.py
@@ -15,18 +15,21 @@ from openviking_cli.exceptions import (
from openviking_cli.session.user_id import UserIdentifier
-class _PathLockClient:
+class _LockManager:
def __init__(self):
self.held = False
self.releases = 0
- async def pathlock_acquire_tree(self, path):
- del path
+ def create_handle(self):
+ return object()
+
+ async def acquire_tree(self, handle, path):
+ del handle, path
self.held = True
- return {"lease_ref": "lock-1"}
+ return True
- async def pathlock_release(self, lease):
- assert lease == {"lease_ref": "lock-1"}
+ async def release(self, handle):
+ del handle
self.held = False
self.releases += 1
@@ -37,7 +40,6 @@ 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
@@ -64,9 +66,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, lease_ref=None):
+ async def write_file(self, uri, content, ctx=None, lock_handle=None):
del ctx
- assert lease_ref is not None
+ assert lock_handle is not None
if uri == self.fail_uri:
raise OSError("injected write failure")
self.files[uri] = content
@@ -86,9 +88,10 @@ 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):
@@ -127,9 +130,10 @@ 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):
@@ -158,10 +162,12 @@ 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
@@ -229,9 +235,10 @@ 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):
@@ -263,8 +270,10 @@ 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 0a7949154..32a4f9735 100644
--- a/tests/server/test_content_write_service.py
+++ b/tests/server/test_content_write_service.py
@@ -3,15 +3,13 @@
"""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 LockAcquisitionError, ResourceBusyError
+from openviking.storage.errors import ResourceBusyError
from openviking_cli.exceptions import (
AlreadyExistsError,
DeadlineExceededError,
@@ -290,25 +288,36 @@ async def test_memory_rm_refreshes_nested_schema_overview(service):
assert "[越前龙马-keep-test](./越前龙马-keep-test.md)" in after
-class _FakePathLock:
- """Mock for _async_agfs pathlock operations."""
+class _FakeHandle:
+ def __init__(self, handle_id: str):
+ self.id = handle_id
+
- 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
+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
self.release_calls = []
- 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
+ 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_release(self, lease):
- self.release_calls.append(lease.id)
+ async def release(self, handle):
+ self.release_calls.append(handle.id)
class _FakeVikingFS:
@@ -321,7 +330,6 @@ 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
@@ -346,13 +354,13 @@ class _FakeVikingFS:
del ctx
return self.content[uri]
- async def write_file(self, uri: str, content: str, ctx=None, lock_handle=None, lease_ref=None):
+ async def write_file(self, uri: str, content: str, ctx=None, lock_handle=None):
del ctx
- self.write_file_calls.append((uri, content, lease_ref or lock_handle))
+ self.write_file_calls.append((uri, content, lock_handle))
self.content[uri] = content
- async def rm(self, uri: str, ctx=None, lock_handle=None, lease_ref=None):
- del ctx, lock_handle, lease_ref
+ async def rm(self, uri: str, ctx=None, lock_handle=None):
+ del ctx, lock_handle
self.rm_calls.append(uri)
self.content.pop(uri, None)
@@ -431,6 +439,12 @@ 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
@@ -451,7 +465,7 @@ async def test_write_timeout_after_enqueue_releases_resource_lock(monkeypatch):
wait=True,
)
- assert viking_fs._async_agfs.release_calls == ["lock-1"]
+ assert lock_manager.release_calls == ["lock-1"]
assert viking_fs.delete_temp_calls == []
assert viking_fs.content[file_uri] == "updated"
@@ -462,8 +476,13 @@ 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(
@@ -473,7 +492,7 @@ async def test_resource_write_lock_conflict_raises_resource_busy(monkeypatch):
)
assert exc_info.value.uri == file_uri
- assert viking_fs._async_agfs.release_calls == []
+ assert lock_manager.release_calls == ["lock-1"]
assert viking_fs.content[file_uri] == "original"
@@ -483,8 +502,13 @@ 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(
@@ -494,46 +518,27 @@ async def test_memory_write_lock_conflict_raises_resource_busy(monkeypatch):
)
assert exc_info.value.uri == file_uri
- assert viking_fs._async_agfs.release_calls == []
+ assert lock_manager.release_calls == ["lock-1"]
assert viking_fs.content[file_uri] == "original"
@pytest.mark.asyncio
- "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):
+async def test_write_direct_reuses_outer_lock_handle_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(
@@ -550,8 +555,7 @@ async def test_write_direct_reuses_outer_lease_for_viking_fs(monkeypatch):
)
assert result["uri"] == file_uri
- assert viking_fs.write_file_calls[0][0:2] == (file_uri, "updated")
- assert viking_fs.write_file_calls[0][2].id == "lock-1"
+ assert viking_fs.write_file_calls == [(file_uri, "updated", lock_manager.handle)]
@pytest.mark.asyncio
@@ -561,8 +565,14 @@ 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)
@@ -584,7 +594,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 viking_fs._async_agfs.release_calls == ["lock-1"]
+ assert lock_manager.release_calls == ["lock-1"]
@pytest.mark.asyncio
@@ -594,6 +604,12 @@ 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
@@ -610,12 +626,11 @@ async def test_resource_write_rolls_back_replace_when_enqueue_fails(monkeypatch)
)
assert viking_fs.content[file_uri] == "original"
- assert [call[0:2] for call in viking_fs.write_file_calls] == [
- (file_uri, "updated"),
- (file_uri, "original"),
+ assert viking_fs.write_file_calls == [
+ (file_uri, "updated", lock_manager.handle),
+ (file_uri, "original", lock_manager.handle),
]
- 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"]
+ assert lock_manager.release_calls == ["lock-1"]
@pytest.mark.asyncio
@@ -625,6 +640,12 @@ 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
@@ -642,7 +663,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 viking_fs._async_agfs.release_calls == ["lock-1"]
+ assert lock_manager.release_calls == ["lock-1"]
@pytest.mark.asyncio
@@ -652,9 +673,15 @@ 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, lease_ref=None):
- del uri, content, mode, ctx, lock_handle, lease_ref
+ async def _fake_write_in_place(uri, content, *, mode, ctx, lock_handle=None):
+ del uri, content, mode, ctx, lock_handle
return None
async def _fail_wait_for_request(*, telemetry_id, timeout):
@@ -679,7 +706,7 @@ async def test_memory_write_wait_skips_semantic_queue_and_releases_write_lock(mo
wait=True,
)
- assert viking_fs._async_agfs.release_calls == ["lock-1"]
+ assert lock_manager.release_calls == ["lock-1"]
assert result["semantic_status"] == "skipped"
assert result["vector_status"] == "skipped"
assert result["overview_status"] == "complete"
@@ -707,7 +734,6 @@ 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
@@ -733,17 +759,9 @@ 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,
- lease_ref=None,
- ):
+ async def write_file(self, uri: str, content: str, *, ctx=None, lock_handle=None):
del ctx
- self.write_file_calls.append((uri, content, lease_ref or lock_handle))
+ self.write_file_calls.append((uri, content, lock_handle))
self.content[uri] = content
parent = uri.rsplit("/", 1)[0]
while parent.startswith("viking://") and parent not in self.existing_dirs:
@@ -752,8 +770,8 @@ class _FakeVikingFSForCreate:
break
parent = parent.rsplit("/", 1)[0]
- async def rm(self, uri: str, *, ctx=None, lock_handle=None, lease_ref=None):
- del ctx, lock_handle, lease_ref
+ async def rm(self, uri: str, *, ctx=None, lock_handle=None):
+ del ctx, lock_handle
self.rm_calls.append(uri)
self.content.pop(uri, None)
@@ -768,11 +786,14 @@ 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, lease_ref=None):
- del mode, ctx, lock_handle, lease_ref
+ async def _fake_write_in_place(uri, content, *, mode, ctx, lock_handle=None):
+ del mode, ctx, lock_handle
write_calls.append((uri, content))
return content
@@ -803,12 +824,15 @@ 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, lease_ref=None):
- del mode, ctx, lock_handle, lease_ref
+ async def _fake_write_in_place(uri, content, *, mode, ctx, lock_handle=None):
+ del mode, ctx, lock_handle
write_calls.append((uri, content))
return content
@@ -846,8 +870,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, lease_ref=None):
- del uri, content, mode, ctx, lock_handle, lease_ref
+ async def _fake_write_in_place(uri, content, *, mode, ctx, lock_handle=None):
+ del uri, content, mode, ctx, lock_handle
return None
async def _fake_wait_for_queues(*, timeout):
@@ -869,8 +893,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, lease_ref=None):
- del uri, content, mode, ctx, lock_handle, lease_ref
+ async def _fake_write_in_place(uri, content, *, mode, ctx, lock_handle=None):
+ del uri, content, mode, ctx, lock_handle
return None
async def _fake_wait_for_queues(*, timeout):
@@ -891,11 +915,14 @@ 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, lease_ref=None):
- del mode, ctx, lock_handle, lease_ref
+ async def _fake_write_in_place(uri, content, *, mode, ctx, lock_handle=None):
+ del mode, ctx, lock_handle
write_calls.append((uri, content))
return content
@@ -926,11 +953,16 @@ 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()
- async def _fake_write_in_place(
- uri, content, *, mode, ctx, lock_handle=None, lease_ref=None
- ):
- del uri, mode, ctx, lock_handle, lease_ref
+ _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
return content
async def _fake_wait_for_queues(*, timeout):
@@ -953,9 +985,12 @@ 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, lease_ref=None):
- del uri, mode, ctx, lock_handle, lease_ref
+ async def _fake_write_in_place(uri, content, *, mode, ctx, lock_handle=None):
+ del uri, mode, ctx, lock_handle
return content
refresh_calls = []
@@ -989,6 +1024,9 @@ 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
@@ -1068,11 +1106,14 @@ 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, lease_ref=None):
+ async def _fake_write_in_place(uri, content, *, mode, ctx, lock_handle=None):
# Verify mode="replace" still works
assert mode == "replace"
- del uri, content, ctx, lock_handle, lease_ref
+ del uri, content, ctx, lock_handle
return None
async def _fake_wait_for_queues(*, timeout):
@@ -1096,11 +1137,14 @@ 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, lease_ref=None):
+ async def _fake_write_in_place(uri, content, *, mode, ctx, lock_handle=None):
# Verify mode="append" still works
assert mode == "append"
- del uri, content, ctx, lock_handle, lease_ref
+ del uri, content, ctx, lock_handle
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 d654e1de6..3309da21d 100644
--- a/tests/server/test_request_wait_tracking.py
+++ b/tests/server/test_request_wait_tracking.py
@@ -47,10 +47,6 @@ 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
@@ -72,12 +68,12 @@ class _FakeVikingFS:
del ctx
return self.content[uri]
- async def write_file(self, uri: str, content: str, ctx=None, lease_ref=None):
- del ctx, lease_ref
+ async def write_file(self, uri: str, content: str, ctx=None):
+ del ctx
self.content[uri] = content
- async def rm(self, uri: str, ctx=None, lock_handle=None, lease_ref=None):
- del ctx, lock_handle, lease_ref
+ async def rm(self, uri: str, ctx=None, lock_handle=None):
+ del ctx, lock_handle
self.content.pop(uri, None)
@@ -267,7 +263,16 @@ 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,
@@ -318,7 +323,16 @@ 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 bd568f7bf..8ca48f7cb 100644
--- a/tests/service/test_reindex_file_lock.py
+++ b/tests/service/test_reindex_file_lock.py
@@ -8,6 +8,7 @@ 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
@@ -38,6 +39,7 @@ 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(
@@ -63,7 +65,8 @@ async def test_reindex_single_file_uri_acquires_tree_lock_without_not_a_director
ctx=ctx,
)
finally:
- pass
+ await release_all_locks()
+ reset_lock_manager()
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 6de281b86..7444e87a9 100644
--- a/tests/service/test_resource_service_understanding_routing.py
+++ b/tests/service/test_resource_service_understanding_routing.py
@@ -34,11 +34,10 @@ async def test_extensionless_remote_url_queues_frozen_understanding_route(
},
is_temporary=True,
)
- lock = {"lease_ref": "lock-1"}
- agfs = SimpleNamespace(
- pathlock_to_handoff=AsyncMock(return_value={"handle_id": "lock-1"}),
- pathlock_handoff=AsyncMock(),
- pathlock_release=AsyncMock(),
+ lock = SimpleNamespace(
+ to_handoff=lambda: SimpleNamespace(to_dict=lambda: {"handle_id": "lock-1"}),
+ handoff=AsyncMock(),
+ close=AsyncMock(),
)
processor = SimpleNamespace(
understanding_api_enabled=lambda: True,
@@ -59,7 +58,7 @@ async def test_extensionless_remote_url_queues_frozen_understanding_route(
)
service = ResourceService(
vikingdb=object(),
- viking_fs=SimpleNamespace(_async_agfs=agfs),
+ viking_fs=object(),
resource_processor=processor,
skill_processor=object(),
)
@@ -79,6 +78,10 @@ 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",
@@ -103,5 +106,4 @@ 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()
- agfs.pathlock_to_handoff.assert_awaited_once_with(lock)
- agfs.pathlock_handoff.assert_awaited_once_with(lock)
+ lock.handoff.assert_awaited_once()
diff --git a/tests/session/memory/test_compressor_v2.py b/tests/session/memory/test_compressor_v2.py
index 522327bab..c17f0e9dd 100644
--- a/tests/session/memory/test_compressor_v2.py
+++ b/tests/session/memory/test_compressor_v2.py
@@ -477,6 +477,8 @@ 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,
@@ -511,6 +513,8 @@ 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,
@@ -582,6 +586,8 @@ 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()),
@@ -676,6 +682,12 @@ 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 == {}
@@ -686,6 +698,8 @@ 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(
@@ -733,6 +747,8 @@ 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
@@ -740,9 +756,14 @@ 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.session.compressor_v2.get_viking_fs", return_value=viking_fs):
+ with patch("openviking.storage.transaction.get_lock_manager", return_value=lock_manager):
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 a1217a21b..62cef1c13 100644
--- a/tests/session/memory/test_memory_updater.py
+++ b/tests/session/memory/test_memory_updater.py
@@ -174,6 +174,7 @@ 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",
@@ -192,11 +193,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):
- self.rm_calls.append((uri, recursive))
+ async def rm(self, uri, recursive=False, ctx=None, lock_handle=None):
+ self.rm_calls.append((uri, recursive, lock_handle))
viking_fs = FakeVikingFS()
- updater = MemoryUpdater(registry=registry)
+ updater = MemoryUpdater(registry=registry, transaction_handle=lock_handle)
updater._get_viking_fs = MagicMock(return_value=viking_fs)
ctx = RequestContext(user=UserIdentifier("acme", "alice"), role=Role.USER)
@@ -210,8 +211,9 @@ class TestMemoryUpdater:
(
"viking://user/alice/memories/entities/动漫角色/.overview.md",
False,
+ lock_handle,
),
- ("viking://user/alice/memories/entities/动漫角色", True),
+ ("viking://user/alice/memories/entities/动漫角色", True, lock_handle),
]
@pytest.mark.asyncio
@@ -234,7 +236,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):
+ async def rm(self, uri, recursive=False, ctx=None, lock_handle=None):
self.rm_calls.append((uri, recursive))
viking_fs = FakeVikingFS()
@@ -306,7 +308,7 @@ class TestMemoryUpdater:
async def read_file(self, uri, ctx=None):
return self.store[uri]
- async def write_file(self, uri, content, ctx=None):
+ async def write_file(self, uri, content, ctx=None, lock_handle=None):
self.store[uri] = content
viking_fs = FakeVikingFS()
@@ -351,7 +353,7 @@ class TestMemoryUpdater:
async def read_file(self, uri, ctx=None):
return self.store[uri]
- async def write_file(self, uri, content, ctx=None):
+ async def write_file(self, uri, content, ctx=None, lock_handle=None):
self.store[uri] = content
viking_fs = FakeVikingFS()
@@ -465,7 +467,8 @@ 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
@@ -507,7 +510,9 @@ 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)
@@ -1079,14 +1084,18 @@ 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 written_content
+ nonlocal write_kwargs, 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)
@@ -1100,6 +1109,7 @@ 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 868c411b7..9ed194543 100644
--- a/tests/session/test_session_commit.py
+++ b/tests/session/test_session_commit.py
@@ -8,11 +8,14 @@ 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:
@@ -686,3 +689,20 @@ 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 cbcdd09cd..a108f8432 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 for training integration tests."""
+ """Tiny synchronous AGFS fake with enough semantics for PathLockEngine."""
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 53c63465e..c67ea77cd 100644
--- a/tests/session/train/test_policy_optimization_real_llm_e2e.py
+++ b/tests/session/train/test_policy_optimization_real_llm_e2e.py
@@ -30,6 +30,7 @@ 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
@@ -533,11 +534,10 @@ def _print_iterative_real_llm_summary(
tracer.info("\n".join(lines), console=True)
-def _patch_experience_prefetch(monkeypatch, fs: InMemoryVikingFS, experience_uri: str) -> None:
- """Patch experience prefetch so the test reads from the in-memory filesystem."""
-
+def _patch_experience_prefetch(
+ monkeypatch, fs: InMemoryVikingFS, experience_uri: str
+) -> None:
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,6 +603,8 @@ 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",
@@ -671,10 +673,14 @@ 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"]
@@ -719,6 +725,8 @@ 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 6b7f4ce62..c3f09f4af 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 fake_request_context
+from test_fakes import InMemoryAGFS, fake_request_context
from openviking.message import Message, TextPart
from openviking.session.memory.dataclass import StoredLink
@@ -34,6 +34,15 @@ 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:
@@ -454,9 +463,7 @@ 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()]),
@@ -492,10 +499,9 @@ 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",
@@ -546,7 +552,6 @@ 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] = []
@@ -866,8 +871,12 @@ 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
@@ -1112,7 +1121,6 @@ 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 = []
@@ -1571,7 +1579,12 @@ 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())
@@ -1595,22 +1608,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(
@@ -1658,7 +1671,12 @@ 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 08cbb637f..bfbf6c714 100644
--- a/tests/storage/test_ingest_ls_node_limit.py
+++ b/tests/storage/test_ingest_ls_node_limit.py
@@ -18,6 +18,7 @@ from __future__ import annotations
import pytest
from openviking.storage.queuefs.semantic_processor import SemanticProcessor
+from openviking.storage.transaction import NO_LOCK
class _TruncatingVikingFS:
@@ -42,16 +43,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, lease_ref=None):
+ async def mv(self, src, dst, ctx=None, lock_handle=None):
self.moved.append((src, dst))
- async def rm(self, uri, recursive=False, ctx=None, lease_ref=None):
+ async def rm(self, uri, recursive=False, ctx=None, lock_handle=None):
pass
- async def mkdir(self, uri, exist_ok=False, ctx=None, lease_ref=None):
+ async def mkdir(self, uri, exist_ok=False, ctx=None):
pass
- async def delete_temp(self, uri, ctx=None, lease_ref=None):
+ async def delete_temp(self, uri, ctx=None):
pass
@@ -67,7 +68,7 @@ async def test_sync_materializes_all_children_above_default_node_limit(monkeypat
diff = await SemanticProcessor()._sync_topdown_recursive(
_TruncatingVikingFS.TEMP,
_TruncatingVikingFS.TARGET,
- lock=None,
+ lock=NO_LOCK,
)
assert len(fake.moved) == n_children, (
diff --git a/tests/storage/test_lock_observer.py b/tests/storage/test_lock_observer.py
new file mode 100644
index 000000000..84580886d
--- /dev/null
+++ b/tests/storage/test_lock_observer.py
@@ -0,0 +1,51 @@
+# 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 628851c62..ef6f58e92 100644
--- a/tests/storage/test_memory_semantic_stall.py
+++ b/tests/storage/test_memory_semantic_stall.py
@@ -15,6 +15,17 @@ 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 = {
@@ -230,6 +241,7 @@ 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 38527ed54..ab69653b8 100644
--- a/tests/storage/test_semantic_dag_incremental.py
+++ b/tests/storage/test_semantic_dag_incremental.py
@@ -11,6 +11,22 @@ 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()}
@@ -94,6 +110,7 @@ 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 a195a4210..69448e97d 100644
--- a/tests/storage/test_semantic_dag_skip_files.py
+++ b/tests/storage/test_semantic_dag_skip_files.py
@@ -1,6 +1,8 @@
# 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
@@ -8,6 +10,23 @@ 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
@@ -74,6 +93,7 @@ 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},
@@ -114,6 +134,7 @@ 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 aec37012c..31b057edf 100644
--- a/tests/storage/test_semantic_dag_stats.py
+++ b/tests/storage/test_semantic_dag_stats.py
@@ -2,6 +2,7 @@
# SPDX-License-Identifier: AGPL-3.0
import asyncio
+from unittest.mock import AsyncMock, MagicMock
import pytest
@@ -106,6 +107,21 @@ 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(
@@ -125,11 +141,7 @@ 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"]
)
@@ -231,6 +243,20 @@ 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 09d3f5b3c..267ec7fe2 100644
--- a/tests/storage/test_semantic_processor_lock_ownership.py
+++ b/tests/storage/test_semantic_processor_lock_ownership.py
@@ -5,55 +5,280 @@ 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 _FakePathLock:
- """Mock for _async_agfs pathlock operations."""
+class _FakeHandle:
+ def __init__(self, handle_id: str):
+ self.id = handle_id
+ self.locks = ["/fake/root/.path.ovlock"]
+
+class _FakeLockManager:
def __init__(self):
- self.release_calls: list[str] = []
+ self._handles = {"lock-1": _FakeHandle("lock-1")}
+ self.release_calls = []
- async def pathlock_release(self, lease):
- self.release_calls.append(lease["id"])
+ 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)
-class _FakeVikingFS:
- def __init__(self, pathlock=None):
- self._async_agfs = pathlock or _FakePathLock()
+ 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)
+
+ 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)
+
+
+class _FakeVikingFS:
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_memory_semantic_directory_does_not_release_borrowed_lock(monkeypatch):
+async def test_semantic_processor_borrows_caller_owned_lock(monkeypatch):
processor = SemanticProcessor()
- pathlock = _FakePathLock()
- borrowed_lease = {"id": "borrowed-lock", "owned": False}
+ 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()
monkeypatch.setattr(
"openviking.storage.queuefs.semantic_processor.get_viking_fs",
- lambda: _FakeVikingFS(pathlock),
+ 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,
)
- await processor._process_memory_directory(
+ await processor.on_dequeue(
SemanticMsg(
- uri="viking://memory/demo",
- context_type="memory",
+ uri="viking://resources/demo",
+ context_type="resource",
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",),
),
- lock=borrowed_lease,
+ fallback_path_factory=lambda: "/local/default/resources/demo",
)
- assert pathlock.release_calls == []
+ 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
diff --git a/tests/storage/test_semantic_processor_mv_vector_store.py b/tests/storage/test_semantic_processor_mv_vector_store.py
index ea0011c87..015861819 100644
--- a/tests/storage/test_semantic_processor_mv_vector_store.py
+++ b/tests/storage/test_semantic_processor_mv_vector_store.py
@@ -1,3 +1,4 @@
+from contextlib import asynccontextmanager
from unittest.mock import AsyncMock
import pytest
@@ -17,6 +18,13 @@ 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 f0b70bed4..109d33a55 100644
--- a/tests/storage/test_semantic_processor_target_preexisting.py
+++ b/tests/storage/test_semantic_processor_target_preexisting.py
@@ -5,6 +5,7 @@ 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:
@@ -35,7 +36,6 @@ class _SyncVikingFS:
],
}
self.deleted_temp = []
- self.mutation_leases = []
async def exists(self, uri, ctx=None):
return uri in self.entries
@@ -49,20 +49,16 @@ class _SyncVikingFS:
async def read_file(self, uri, ctx=None):
return self.contents.get(uri, "")
- async def rm(self, uri, recursive=False, ctx=None, lease_ref=None):
- self.mutation_leases.append(("rm", uri, lease_ref))
+ async def rm(self, uri, recursive=False, ctx=None, lock_handle=None):
self.contents.pop(uri, None)
- async def mv(self, src, dst, ctx=None, lease_ref=None):
- self.mutation_leases.append(("mv", dst, lease_ref))
+ async def mv(self, src, dst, ctx=None, lock_handle=None):
self.contents[dst] = self.contents.pop(src)
- async def mkdir(self, uri, exist_ok=False, ctx=None, lease_ref=None):
- self.mutation_leases.append(("mkdir", uri, lease_ref))
+ async def mkdir(self, uri, exist_ok=False, ctx=None):
self.entries.setdefault(uri, [])
- async def delete_temp(self, uri, ctx=None, lease_ref=None):
- self.mutation_leases.append(("delete_temp", uri, lease_ref))
+ async def delete_temp(self, uri, ctx=None):
self.deleted_temp.append(uri)
@@ -97,7 +93,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=None, close=AsyncMock())),
+ AsyncMock(return_value=SimpleNamespace(lock=NO_LOCK, close=AsyncMock())),
)
_FakeDagExecutor.calls = []
@@ -131,11 +127,6 @@ 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,
@@ -144,7 +135,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=lease,
+ lock=NO_LOCK,
)
assert diff.to_changes() == {
@@ -158,13 +149,6 @@ 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
@@ -180,7 +164,7 @@ async def test_sync_missing_source_never_touches_target(monkeypatch):
await SemanticProcessor()._sync_topdown_recursive(
"viking://temp/missing",
"viking://resources/root",
- lock=None,
+ lock=NO_LOCK,
)
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 c69c4320b..d8a810cda 100644
--- a/tests/storage/test_semantic_queue_memory_dedupe.py
+++ b/tests/storage/test_semantic_queue_memory_dedupe.py
@@ -101,24 +101,38 @@ async def test_coalesced_semantic_messages_mark_old_version_stale():
assert not is_semantic_msg_stale(second)
-class _FakePathLock:
- """Mock for _async_agfs pathlock operations."""
+class _FakeHandle:
+ def __init__(self):
+ self.id = "lock-1"
+ self.locks = []
+
+class _FakeLockManager:
def __init__(self):
self.acquired_batches = []
self.release_calls = []
- async def pathlock_acquire_exact_batch(self, paths):
+ 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):
self.acquired_batches.append(paths)
- return {"id": "lock-1"}
+ handle.locks.extend(paths)
+ return True
+
+ async def release(self, handle):
+ self.release_calls.append(handle.id)
- async def pathlock_release(self, lease):
- self.release_calls.append(lease["id"])
+ async def release_selected(self, handle, lock_paths):
+ del handle, lock_paths
class _FakeVikingFS:
- def __init__(self, pathlock=None):
- self._async_agfs = pathlock or _FakePathLock()
+ def __init__(self):
self.writes = []
def _uri_to_path(self, uri, ctx=None):
@@ -141,8 +155,8 @@ class _FakeMemoryDirFS:
@pytest.mark.asyncio
async def test_stale_memory_semantic_write_is_skipped(monkeypatch):
- pathlock = _FakePathLock()
- viking_fs = _FakeVikingFS(pathlock)
+ lock_manager = _FakeLockManager()
+ viking_fs = _FakeVikingFS()
processor = SemanticProcessor()
coalesce_key = f"memory|acc|u|p|viking://user/default/memories/preferences/{uuid4().hex}"
@@ -161,6 +175,8 @@ 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,
@@ -180,7 +196,7 @@ async def test_stale_memory_semantic_write_is_skipped(monkeypatch):
assert not wrote_first
assert wrote_latest
- assert pathlock.acquired_batches == [
+ assert lock_manager.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
new file mode 100644
index 000000000..920e53f07
--- /dev/null
+++ b/tests/storage/test_viking_fs_async_stat.py
@@ -0,0 +1,36 @@
+# 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 9033f3074..4b00e7407 100644
--- a/tests/storage/test_viking_fs_tree.py
+++ b/tests/storage/test_viking_fs_tree.py
@@ -12,9 +12,7 @@ from openviking_cli.session.user_id import UserIdentifier
class _DummyAgfs:
- def stat(self, _path, ctx=None):
- """Return a minimal stat payload for paths assumed to exist in tree tests."""
- return {}
+ pass
class _FixedDatetime(datetime):
@@ -138,7 +136,7 @@ async def default_batch_fetch(entries, abs_limit, **_kwargs):
[
("resources", "/local/test_account", True),
("user", "/local/test_account", True),
- ("agent", "/local/test_account", True),
+ ("agent", "/local/test_account", False),
("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 6e1d22986..6765cb9ed 100644
--- a/tests/storage/test_viking_fs_write_locking.py
+++ b/tests/storage/test_viking_fs_write_locking.py
@@ -1,10 +1,6 @@
-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:
@@ -29,93 +25,63 @@ class _FakeAGFS:
return self.storage[path]
-class _AsyncAppendAGFS:
- """Async AGFS stub that records append lock ordering."""
-
- def __init__(self):
- self.events = []
-
- 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 pathlock_release(self, lease):
- """Record lease release."""
- self.events.append(("release", lease))
-
- 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)
+class _RecordingLockContext:
+ """Record LockContext arguments so tests can assert dual-path locking."""
+ calls = []
-class _AsyncMoveAGFS:
- """Async AGFS stub that records move lock ownership and release."""
+ 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
- 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
+ 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 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 __aexit__(self, exc_type, exc, tb):
+ """Do not swallow exceptions on exit."""
+ return False
- 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,
- }
+ ("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
- async def pathlock_release(self, lease):
- """Record operation lease release."""
- self.release_calls.append(lease)
+ _RecordingLockContext.calls.clear()
+ monkeypatch.setattr(transaction_module, "LockContext", _RecordingLockContext)
+ monkeypatch.setattr(transaction_module, "get_lock_manager", lambda: object())
- 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}
+ agfs = _FakeAGFS()
+ agfs.storage["/local/default/resources/note.md"] = b"hello"
+ fs = VikingFS(agfs=agfs, encryptor=object())
+ await getattr(fs, method_name)("viking://resources/note.md", *args)
-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))
+ 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
@pytest.mark.parametrize(
@@ -147,190 +113,3 @@ 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
new file mode 100644
index 000000000..a853cb253
--- /dev/null
+++ b/tests/transaction/test_concurrent_lock.py
@@ -0,0 +1,103 @@
+# 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
new file mode 100644
index 000000000..0e6dd4453
--- /dev/null
+++ b/tests/transaction/test_e2e.py
@@ -0,0 +1,126 @@
+# 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
new file mode 100644
index 000000000..e5f1b63f3
--- /dev/null
+++ b/tests/transaction/test_exact_path_lock.py
@@ -0,0 +1,244 @@
+# 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
new file mode 100644
index 000000000..a29580caa
--- /dev/null
+++ b/tests/transaction/test_lock_context.py
@@ -0,0 +1,110 @@
+# 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
new file mode 100644
index 000000000..209e9a816
--- /dev/null
+++ b/tests/transaction/test_lock_manager.py
@@ -0,0 +1,132 @@
+# 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
new file mode 100644
index 000000000..92dd87f5c
--- /dev/null
+++ b/tests/transaction/test_lock_manager_staleness.py
@@ -0,0 +1,80 @@
+# 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
new file mode 100644
index 000000000..39986e732
--- /dev/null
+++ b/tests/transaction/test_lock_reentrancy_unit.py
@@ -0,0 +1,141 @@
+# 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
new file mode 100644
index 000000000..fd2dd2a75
--- /dev/null
+++ b/tests/transaction/test_path_lock.py
@@ -0,0 +1,689 @@
+# 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 a80f7a07e..9e87a3c3a 100644
--- a/tests/unit/test_resource_reservation.py
+++ b/tests/unit/test_resource_reservation.py
@@ -25,6 +25,10 @@ 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 14dc7bdef..274f03aa4 100644
--- a/tests/utils/test_resource_processor_processing_mode.py
+++ b/tests/utils/test_resource_processor_processing_mode.py
@@ -49,7 +49,6 @@ 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 +77,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 = {"lease_ref": "lock-1"}
+ lock = SimpleNamespace(active=True, handle="lock-1", close=AsyncMock())
result = await processor.finish_prepared_resource(
{
@@ -95,15 +94,12 @@ 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,
- lease_ref=lock,
+ "viking://temp/demo", "viking://resources/demo", ctx=ctx
)
rewrite_image_uris.assert_awaited_once_with(
"viking://resources/demo",
ctx=ctx,
- lease_ref=lock,
+ lock_handle="lock-1",
)
viking_fs.delete_temp.assert_awaited_once_with("tmp/demo", ctx=ctx)
vectorize_file.assert_awaited_once()
@@ -118,13 +114,12 @@ 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()
- viking_fs._async_agfs.pathlock_release.assert_awaited_once_with(lock)
+ lock.close.assert_awaited_once()
@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=[]),
@@ -136,7 +131,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 = {"lease_ref": "lock-1"}
+ lock = SimpleNamespace(active=True, handle="lock-1", close=AsyncMock())
await processor.finish_prepared_resource(
{
@@ -158,7 +153,6 @@ 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 +168,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 = {"lease_ref": "lock-1"}
+ lock = SimpleNamespace(active=True, handle="lock-1", close=AsyncMock())
await processor.finish_prepared_resource(
{
@@ -202,7 +196,6 @@ 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=[]),
@@ -213,7 +206,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 = {"lease_ref": "lock-1"}
+ lock = SimpleNamespace(active=True, handle="lock-1", close=AsyncMock())
await processor.finish_prepared_resource(
{
@@ -233,7 +226,6 @@ 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=[]),
@@ -253,7 +245,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 = {"lease_ref": "lock-1"}
+ lock = SimpleNamespace(active=True, handle="lock-1", close=AsyncMock())
await processor.finish_prepared_resource(
{