Self-evolving Context Database for AI Agents. Unify Agent Memory, Knowledge RAG and Skills.
Python agent-contextagent-memoryagent-pluginsagentic-ragcontext-databasedsh-pluginknowledge-basememorymemory-managementself-evolvingvector-database
feat(pathlock): pathlock support cache runtime (#4918)
baojun-zhang35c984c449d1
diff --git a/crates/ragfs-python/src/lib.rs b/crates/ragfs-python/src/lib.rsindex a3b8fe467..5f0cef2fa 100644--- a/crates/ragfs-python/src/lib.rs+++ b/crates/ragfs-python/src/lib.rs@@ -197,19 +197,6 @@ fn validate_timeout_secs(v: f64) -> PyResult<Duration> {}}-/// Validate and convert a lock expire duration from Python config.-///-/// Must be finite, positive, and at least 1.0 second.-fn validate_expire_secs(v: f64) -> PyResult<f64> {- if v.is_finite() && v >= 1.0 {- Ok(v)- } else {- Err(PyValueError::new_err(- "lock_expire_secs must be a finite number >= 1.0",- ))- }-}-use ragfs::cache::{CachePolicy, CacheTraversalMode};use ragfs::cache_runtime::{CacheRuntime, DynamicProviderConfig, RedisProviderConfig};use ragfs::core::builder::{@@ -439,6 +426,89 @@ impl RagfsCacheConfig {}}+/// Load PathLock configuration from one canonical OpenViking config file.+fn pathlock_config_from_ov_conf(path: &str) -> Result<PathLockConfig, String> {+ let raw = fs::read_to_string(path)+ .map_err(|error| format!("failed to read OpenViking config {path}: {error}"))?;+ let json: serde_json::Value = serde_json::from_str(&raw)+ .map_err(|error| format!("failed to parse OpenViking config {path}: {error}"))?;+ pathlock_config_from_canonical_ov_conf(&json)+}++/// Parse PathLock configuration from the canonical `storage.agfs.pathlock` section.+fn pathlock_config_from_canonical_ov_conf(+ json: &serde_json::Value,+) -> Result<PathLockConfig, String> {+ let pathlock = json+ .get("storage")+ .and_then(|storage| storage.get("agfs"))+ .and_then(|agfs| agfs.get("pathlock"));+ match pathlock {+ Some(pathlock) => pathlock_config_from_value(pathlock),+ None => Ok(PathLockConfig::default()),+ }+}++/// Parse one sectioned PathLock configuration object.+fn pathlock_config_from_value(value: &serde_json::Value) -> Result<PathLockConfig, String> {+ let pathlock = value+ .as_object()+ .ok_or_else(|| "pathlock config must be an object".to_string())?;+ const FIELDS: &[&str] = &[+ "provider",+ "namespace",+ "lock_timeout_secs",+ "lock_expire_secs",+ ];+ if let Some(field) = pathlock+ .keys()+ .find(|field| !FIELDS.contains(&field.as_str()))+ {+ return Err(format!("unsupported pathlock field: {field}"));+ }++ let provider = string_field(pathlock, "provider", "filesystem")?;+ if !matches!(provider.as_str(), "filesystem" | "memory" | "cache") {+ return Err(format!(+ "unsupported pathlock.provider: {provider}; expected filesystem, memory, or cache"+ ));+ }+ let namespace = optional_string_field(pathlock, "namespace")?;+ if provider == "cache" && namespace.as_deref().is_none_or(str::is_empty) {+ return Err("pathlock.namespace is required for provider=cache".to_string());+ }+ if let Some(namespace) = &namespace {+ if !namespace+ .bytes()+ .all(|byte| byte.is_ascii_alphanumeric() || matches!(byte, b'.' | b'_' | b'-'))+ {+ return Err(+ "pathlock.namespace must contain only ASCII letters, digits, '.', '_' or '-'"+ .to_string(),+ );+ }+ }++ let lock_timeout_secs =+ f64_field(pathlock, "lock_timeout_secs", 0.0)?;+ if !lock_timeout_secs.is_finite() || lock_timeout_secs < 0.0 {+ return Err(+ "pathlock.lock_timeout_secs must be a finite non-negative number".to_string(),+ );+ }+ let lock_expire_secs = f64_field(pathlock, "lock_expire_secs", 30.0)?;+ if !lock_expire_secs.is_finite() || lock_expire_secs < 1.0 {+ return Err("pathlock.lock_expire_secs must be finite and >= 1.0".to_string());+ }++ Ok(PathLockConfig {+ provider,+ namespace,+ lock_timeout_secs,+ lock_expire_secs,+ })+}+fn cache_config_from_ov_conf(path: &str) -> Result<RagfsCacheConfig, String> {let raw = fs::read_to_string(path).map_err(|error| format!("failed to read OpenViking config {path}: {error}"))?;@@ -447,8 +517,30 @@ fn cache_config_from_ov_conf(path: &str) -> Result<RagfsCacheConfig, String> {cache_config_from_canonical_ov_conf(&json)}+/// Load canonical cache configuration while forcing a shared Runtime consumer.+fn cache_config_from_ov_conf_with_runtime(+ path: &str,+ force_runtime: bool,+) -> Result<RagfsCacheConfig, String> {+ let raw = fs::read_to_string(path)+ .map_err(|error| format!("failed to read OpenViking config {path}: {error}"))?;+ let json: serde_json::Value = serde_json::from_str(&raw)+ .map_err(|error| format!("failed to parse OpenViking config {path}: {error}"))?;+ cache_config_from_canonical_ov_conf_with_runtime(&json, force_runtime)+}+fn cache_config_from_canonical_ov_conf(json: &serde_json::Value,+) -> Result<RagfsCacheConfig, String> {+ let pathlock_uses_cache =+ pathlock_config_from_canonical_ov_conf(json)?.provider == "cache";+ cache_config_from_canonical_ov_conf_with_runtime(json, pathlock_uses_cache)+}++/// Parse canonical cache configuration and optionally require its shared Runtime.+fn cache_config_from_canonical_ov_conf_with_runtime(+ json: &serde_json::Value,+ force_runtime: bool,) -> Result<RagfsCacheConfig, String> {let agfs = json.get("storage").and_then(|storage| storage.get("agfs"));if agfs.and_then(|agfs| agfs.get("cache")).is_some() {@@ -484,7 +576,7 @@ fn cache_config_from_canonical_ov_conf(let mut config = RagfsCacheConfig::default();config.enabled = cachefs_backend == "cache";- config.runtime_enabled = config.enabled || queuefs_backend == "cache";+ config.runtime_enabled = config.enabled || queuefs_backend == "cache" || force_runtime;if let Some(cachefs) = cachefs {let cachefs = cachefs.as_object()@@ -526,6 +618,11 @@ fn cache_config_from_canonical_ov_conf(match config.provider {CacheProviderKind::Redis => parse_redis_config(&mut config.redis, ¶ms, "cache.params")?,CacheProviderKind::Dynamic => {+ if force_runtime {+ return Err(+ "cache-backed PathLock requires top-level cache.provider=redis".to_string(),+ );+ }parse_dynamic_config(&mut config.dynamic, ¶ms)?;}}@@ -708,6 +805,20 @@ fn string_field(}}+/// Read a floating-point field or return its default.+fn f64_field(+ object: &serde_json::Map<String, serde_json::Value>,+ key: &str,+ default: f64,+) -> Result<f64, String> {+ match object.get(key) {+ Some(value) => value+ .as_f64()+ .ok_or_else(|| format!("{key} must be a number")),+ None => Ok(default),+ }+}+fn optional_string_field(object: &serde_json::Map<String, serde_json::Value>,key: &str,@@ -1351,6 +1462,16 @@ impl RAGFSBindingClient {// Phase A (holding GIL): parse the sectioned config into an owned RagfsConfig.let mut ragfs_cfg = RagfsConfig::default();+ let inline_pathlock_configured = config+ .as_ref()+ .is_some_and(|config| config.contains_key("pathlock"));+ if !inline_pathlock_configured {+ if let Some(path) = config_path {+ ragfs_cfg.pathlock = pathlock_config_from_ov_conf(path).map_err(|error| {+ PyRuntimeError::new_err(format!("Invalid PathLock config: {error}"))+ })?;+ }+ }let mut runtime_cache_config = None;let mut inline_git_cfg: Option<ragfs::git::GitConfig> = None;if let Some(cfg) = config {@@ -1402,43 +1523,43 @@ impl RAGFSBindingClient {}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(30.0),- )?;- let lock_timeout_secs = validate_timeout_secs(- pl_value- .get("lock_timeout_secs")- .and_then(|v| v.as_f64())- .unwrap_or(0.0),- )?- .as_secs_f64();- ragfs_cfg.pathlock = PathLockConfig {- provider: provider.to_string(),- lock_timeout_secs,- lock_expire_secs,- };+ ragfs_cfg.pathlock = pathlock_config_from_value(&pl_value)+ .map_err(PyValueError::new_err)?;}}+ let inline_cache_configured = runtime_cache_config.is_some();+ let pathlock_uses_cache = ragfs_cfg.pathlock.provider == "cache";let file_cache_config = config_path- .map(cache_config_from_ov_conf)+ .map(|path| {+ if inline_cache_configured {+ cache_config_from_ov_conf_with_runtime(path, false)+ } else if inline_pathlock_configured {+ cache_config_from_ov_conf_with_runtime(path, pathlock_uses_cache)+ } else {+ cache_config_from_ov_conf(path)+ }+ }).transpose().map_err(|error| PyRuntimeError::new_err(format!("Invalid cache config: {error}")))?;- let cache_config = runtime_cache_config+ let mut cache_config = runtime_cache_config.or(file_cache_config).unwrap_or_default();+ if pathlock_uses_cache {+ if cache_config.provider != CacheProviderKind::Redis {+ return Err(PyValueError::new_err(+ "cache-backed PathLock requires cache.provider=redis",+ ));+ }+ if inline_cache_configured {+ cache_config.runtime_enabled = true;+ }+ if !cache_config.runtime_enabled {+ return Err(PyValueError::new_err(+ "top-level cache config is required for cache-backed PathLock",+ ));+ }+ }// Phase B: RAGFS owns Runtime construction and injects the same instance// into CacheFS and QueueFS. The binding only translates configuration.@@ -2941,6 +3062,86 @@ mod tests {fs::remove_file(path).unwrap();}+ #[test]+ fn constructor_inline_pathlock_overrides_canonical_pathlock() {+ Python::initialize();+ let path = std::env::temp_dir().join(format!(+ "openviking-inline-pathlock-override-{}.json",+ std::process::id()+ ));+ fs::write(+ &path,+ r#"{+ "storage": {+ "agfs": {+ "pathlock": {"provider": "cache"}+ }+ }+ }"#,+ )+ .unwrap();++ Python::attach(|py| {+ let ty = py.get_type::<RAGFSBindingClient>();+ let pathlock = PyDict::new(py);+ pathlock.set_item("provider", "filesystem").unwrap();+ let config = PyDict::new(py);+ config.set_item("pathlock", pathlock).unwrap();+ let kwargs = PyDict::new(py);+ kwargs+ .set_item("config_path", path.to_str().unwrap())+ .unwrap();+ kwargs.set_item("config", config).unwrap();++ let instance = ty.call((), Some(&kwargs));+ assert!(instance.is_ok());+ });++ fs::remove_file(path).unwrap();+ }++ #[test]+ fn constructor_inline_redis_pathlock_uses_inline_cache() {+ let Ok(endpoint) = std::env::var("REDIS_URL") else {+ return;+ };+ Python::initialize();+ let path = std::env::temp_dir().join(format!(+ "openviking-inline-redis-pathlock-{}.json",+ std::process::id()+ ));+ fs::write(&path, r#"{"storage": {"agfs": {"backend": "local"}}}"#).unwrap();++ Python::attach(|py| {+ let ty = py.get_type::<RAGFSBindingClient>();+ let redis = PyDict::new(py);+ redis.set_item("endpoints", vec![endpoint]).unwrap();+ redis.set_item("command_timeout_ms", 1_000).unwrap();+ let cache = PyDict::new(py);+ cache.set_item("enabled", false).unwrap();+ cache.set_item("runtime_enabled", false).unwrap();+ cache.set_item("provider", "redis").unwrap();+ cache.set_item("redis", redis).unwrap();+ let pathlock = PyDict::new(py);+ pathlock.set_item("provider", "cache").unwrap();+ pathlock.set_item("namespace", "inline-prod").unwrap();+ pathlock.set_item("lock_expire_secs", 3.0).unwrap();+ let config = PyDict::new(py);+ config.set_item("cache", cache).unwrap();+ config.set_item("pathlock", pathlock).unwrap();+ let kwargs = PyDict::new(py);+ kwargs+ .set_item("config_path", path.to_str().unwrap())+ .unwrap();+ kwargs.set_item("config", config).unwrap();++ let instance = ty.call((), Some(&kwargs));+ assert!(instance.is_ok());+ });++ fs::remove_file(path).unwrap();+ }+#[test]fn parse_tracing_level_accepts_critical_as_error() {assert_eq!(parse_tracing_level("CRITICAL").unwrap(), Level::ERROR);@@ -3001,6 +3202,59 @@ mod tests {fs::remove_file(path).unwrap();}+ #[test]+ fn canonical_redis_pathlock_config_is_parsed_and_enables_runtime() {+ let path = std::env::temp_dir().join(format!(+ "openviking-redis-pathlock-config-{}.json",+ std::process::id()+ ));+ fs::write(+ &path,+ r#"{+ "cache": {+ "provider": "redis",+ "params": {"endpoints": ["redis://redis:6379"]}+ },+ "storage": {+ "agfs": {+ "pathlock": {+ "provider": "cache",+ "namespace": "prod-a",+ "lock_expire_secs": 60.0+ }+ }+ }+ }"#,+ )+ .unwrap();++ let pathlock = pathlock_config_from_ov_conf(path.to_str().unwrap()).unwrap();+ let cache = cache_config_from_ov_conf(path.to_str().unwrap()).unwrap();++ assert_eq!(pathlock.provider, "cache");+ assert_eq!(pathlock.namespace.as_deref(), Some("prod-a"));+ assert_eq!(pathlock.lock_expire_secs, 60.0);+ assert!(cache.runtime_enabled);+ assert_eq!(cache.provider, CacheProviderKind::Redis);+ assert_eq!(cache.redis.endpoints, vec!["redis://redis:6379"]);++ fs::remove_file(path).unwrap();+ }++ #[test]+ fn redis_pathlock_config_requires_namespace() {+ let error = pathlock_config_from_canonical_ov_conf(&serde_json::json!({+ "storage": {+ "agfs": {+ "pathlock": {"provider": "cache"}+ }+ }+ }))+ .unwrap_err();++ assert!(error.contains("namespace"));+ }+#[test]fn canonical_cache_config_is_parsed_from_ov_conf() {let path = std::env::temp_dir().join(format!(diff --git a/crates/ragfs/src/core/builder.rs b/crates/ragfs/src/core/builder.rsindex ebf9f546b..61c47051e 100644--- a/crates/ragfs/src/core/builder.rs+++ b/crates/ragfs/src/core/builder.rs@@ -14,7 +14,6 @@ use super::filesystem::FileSystem;use super::mountable::MountableFS;use super::stats_wrapper::StatsWrappedFS;-#[cfg(feature = "cache")]use super::errors::{Error, Result};#[cfg(feature = "cache")]use crate::cache::{CacheNamespace, CachePolicy};@@ -27,6 +26,8 @@ use crate::lock::{FilesystemPathLockProvider, MemoryPathLockProvider, PathLockConfig, PathLockManager,PathLockProvider, PathLockWrappedFS,};+#[cfg(feature = "cache")]+use crate::lock::RedisPathLockProvider;#[cfg(feature = "s3")]use crate::plugins::S3FSPlugin;@@ -123,7 +124,7 @@ pub struct RagfsStack {/// 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 {+pub async fn build_default_stack(config: RagfsConfig) -> Result<RagfsStack> {let mountable = Arc::new(MountableFS::new());build_stack_with_mountable(config, mountable).await}@@ -135,7 +136,7 @@ pub async fn build_default_stack(config: RagfsConfig) -> RagfsStack {pub async fn build_stack_with_mountable(config: RagfsConfig,mountable: Arc<MountableFS>,-) -> RagfsStack {+) -> Result<RagfsStack> {build_stack_with_mountable_and_runtime(config, mountable, None).await}@@ -146,11 +147,23 @@ pub async fn build_configured_stack(cache: Option<CacheStackConfig>,) -> Result<RagfsStack> {let Some(cache) = cache else {- return Ok(build_default_stack(config).await);+ return build_default_stack(config).await;};- if cache.cachefs.enabled && cache.provider.is_none() {+ let pathlock_uses_cache = config.pathlock.provider == "cache";+ if (cache.cachefs.enabled || pathlock_uses_cache) && cache.provider.is_none() {return Err(Error::config(- "cache provider is required when CacheFS is enabled".to_string(),+ "cache provider is required when CacheFS or cache-backed PathLock is enabled"+ .to_string(),+ ));+ }+ if pathlock_uses_cache+ && !matches!(+ &cache.provider,+ Some(CacheRuntimeProviderConfig::Redis(_))+ )+ {+ return Err(Error::config(+ "cache-backed PathLock requires the shared cache provider to be redis".to_string(),));}let runtime = match cache.provider {@@ -190,7 +203,7 @@ pub async fn build_configured_stack(} else {Arc::new(MountableFS::new())};- Ok(build_stack_with_mountable_and_runtime(config, mountable, runtime).await)+ build_stack_with_mountable_and_runtime(config, mountable, runtime).await}async fn build_stack_with_mountable_and_runtime(@@ -198,7 +211,7 @@ async fn build_stack_with_mountable_and_runtime(mountable: Arc<MountableFS>,#[cfg(feature = "cache")] runtime: Option<Arc<CacheRuntime>>,#[cfg(not(feature = "cache"))] _runtime: Option<()>,-) -> RagfsStack {+) -> Result<RagfsStack> {#[cfg(feature = "cache")]register_builtin_plugins_with_runtime(&mountable, runtime.clone()).await;#[cfg(not(feature = "cache"))]@@ -212,11 +225,41 @@ async fn build_stack_with_mountable_and_runtime(}let provider: Arc<dyn PathLockProvider> = match config.pathlock.provider.as_str() {- "memory" => Arc::new(MemoryPathLockProvider::new()),- _ => Arc::new(FilesystemPathLockProvider::new(+ "filesystem" => Arc::new(FilesystemPathLockProvider::new(mountable.clone() as Arc<dyn FileSystem>,config.pathlock.lock_expire_secs,)),+ "memory" => Arc::new(MemoryPathLockProvider::new()),+ #[cfg(feature = "cache")]+ "cache" => {+ let runtime = runtime.clone().ok_or_else(|| {+ Error::config("cache provider is required for cache-backed PathLock".to_string())+ })?;+ let namespace = config.pathlock.namespace.as_deref().ok_or_else(|| {+ Error::config("pathlock namespace is required for cache-backed PathLock".to_string())+ })?;+ Arc::new(+ RedisPathLockProvider::new(+ runtime,+ namespace,+ config.pathlock.lock_expire_secs,+ )+ .map_err(|error| {+ Error::config(format!("Redis PathLock initialization failed: {error}"))+ })?,+ )+ }+ #[cfg(not(feature = "cache"))]+ "cache" => {+ return Err(Error::config(+ "cache-backed PathLock requires the ragfs cache feature".to_string(),+ ));+ }+ other => {+ return Err(Error::config(format!(+ "unsupported PathLock provider: {other}"+ )));+ }};let pathlock_manager = Arc::new(PathLockManager::new(mountable.clone() as Arc<dyn FileSystem>,@@ -233,13 +276,13 @@ async fn build_stack_with_mountable_and_runtime());let top: Arc<dyn FileSystem> = Arc::new(StatsWrappedFS::with_arc(inner));- RagfsStack {+ Ok(RagfsStack {mountable,top,pathlock_manager,#[cfg(feature = "cache")]cache_runtime: runtime,- }+ })}/// The single built-in plugin registration sequence (eliminates drift across call sites).@@ -310,6 +353,7 @@ mod tests {}),pathlock: PathLockConfig {provider: "filesystem".to_string(),+ namespace: None,lock_timeout_secs: 0.0,lock_expire_secs: 30.0,},@@ -348,7 +392,7 @@ mod tests {#[tokio::test]async fn encrypted_stack_encrypts_on_disk() {- let stack = build_default_stack(enc_config()).await;+ let stack = build_default_stack(enc_config()).await.unwrap();mount_mem(&stack).await;let ctx = Arc::new(FsContextInner::new("tenant"));@@ -369,7 +413,7 @@ mod tests {#[tokio::test]async fn encrypted_stack_with_pathlock_does_not_reacquire_final_lock() {- let stack = build_default_stack(enc_pathlock_config()).await;+ let stack = build_default_stack(enc_pathlock_config()).await.unwrap();mount_mem(&stack).await;let write = FS_CTX.scope(Arc::new(FsContextInner::new("tenant")), async {@@ -397,7 +441,7 @@ mod tests {#[tokio::test]async fn encrypted_write_extends_outer_lease() {- let stack = build_default_stack(enc_pathlock_config()).await;+ let stack = build_default_stack(enc_pathlock_config()).await.unwrap();mount_mem(&stack).await;let manager = &stack.pathlock_manager;let outer = manager@@ -428,7 +472,7 @@ mod tests {#[tokio::test]async fn encrypted_write_rejects_uncovered_outer_lease() {- let stack = build_default_stack(enc_pathlock_config()).await;+ let stack = build_default_stack(enc_pathlock_config()).await.unwrap();mount_mem(&stack).await;let manager = &stack.pathlock_manager;let outer = manager@@ -461,14 +505,14 @@ mod tests {#[tokio::test]async fn default_stack_initializes_pathlock_manager() {- let stack = build_default_stack(RagfsConfig::default()).await;+ let stack = build_default_stack(RagfsConfig::default()).await.unwrap();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;+ let stack = build_default_stack(RagfsConfig::default()).await.unwrap();mount_mem(&stack).await;// No FS_CTX scope needed; bytes are stored verbatim.@@ -491,6 +535,89 @@ mod tests {assert!(stack.cache_runtime.is_none());}+ #[tokio::test]+ async fn default_stack_rejects_unknown_pathlock_provider() {+ let config = RagfsConfig {+ pathlock: PathLockConfig {+ provider: "unknown".to_string(),+ ..PathLockConfig::default()+ },+ ..RagfsConfig::default()+ };++ let error = match build_default_stack(config).await {+ Ok(_) => panic!("unknown PathLock provider unexpectedly built"),+ Err(error) => error,+ };++ assert!(error.to_string().contains("unknown"));+ }++ #[cfg(feature = "cache")]+ #[tokio::test]+ async fn configured_stack_rejects_redis_pathlock_without_runtime() {+ let config = RagfsConfig {+ pathlock: PathLockConfig {+ provider: "cache".to_string(),+ namespace: Some("builder-test".to_string()),+ ..PathLockConfig::default()+ },+ ..RagfsConfig::default()+ };++ let error = match build_configured_stack(config, None).await {+ Ok(_) => panic!("Redis PathLock unexpectedly built without Runtime"),+ Err(error) => error,+ };++ assert!(error.to_string().contains("cache provider"));+ }++ #[cfg(feature = "cache")]+ #[tokio::test]+ async fn configured_stack_builds_redis_pathlock_with_shared_runtime() {+ let Ok(endpoint) = std::env::var("REDIS_URL") else {+ return;+ };+ let namespace = format!("builder-pathlock-test-{}", std::process::id());+ let config = RagfsConfig {+ pathlock: PathLockConfig {+ provider: "cache".to_string(),+ namespace: Some(namespace),+ lock_expire_secs: 3.0,+ ..PathLockConfig::default()+ },+ ..RagfsConfig::default()+ };+ let stack = build_configured_stack(+ config,+ Some(CacheStackConfig {+ provider: Some(CacheRuntimeProviderConfig::Redis(RedisProviderConfig {+ endpoints: vec![endpoint],+ command_timeout_ms: 1_000,+ ..RedisProviderConfig::default()+ })),+ cachefs: CacheFsConfig::default(),+ }),+ )+ .await+ .unwrap();++ let lease = stack+ .pathlock_manager+ .acquire_exact(+ "/local/account-a/builder",+ std::time::Duration::ZERO,+ None,+ )+ .await+ .unwrap();++ assert!(stack.cache_runtime.is_some());+ assert_eq!(lease.lease.lock_paths, vec!["/local/account-a/builder"]);+ stack.pathlock_manager.release(&lease).await.unwrap();+ }+#[cfg(feature = "cache")]#[tokio::test]async fn configured_stack_rejects_cachefs_without_global_provider() {@@ -558,7 +685,7 @@ mod tests {#[tokio::test]async fn encrypted_stack_preserves_queuefs_control_semantics() {- let stack = build_default_stack(enc_config()).await;+ let stack = build_default_stack(enc_config()).await.unwrap();stack.mountable.mount(plugin_config("queuefs", "/queue", HashMap::new()))@@ -586,7 +713,7 @@ mod tests {#[tokio::test]async fn encrypted_mount_writes_backend_shape_guard() {let dir = TempDir::new().unwrap();- let stack = build_default_stack(enc_config()).await;+ let stack = build_default_stack(enc_config()).await.unwrap();mount_local(&stack, "/local", dir.path().to_str().unwrap()).await@@ -610,7 +737,7 @@ mod tests {let dir = TempDir::new().unwrap();fs::write(dir.path().join("legacy.txt"), b"plaintext").unwrap();- let stack = build_default_stack(enc_config()).await;+ let stack = build_default_stack(enc_config()).await.unwrap();let err = mount_local(&stack, "/local", dir.path().to_str().unwrap()).await.unwrap_err();@@ -641,7 +768,7 @@ mod tests {).unwrap();- let stack = build_default_stack(enc_config()).await;+ let stack = build_default_stack(enc_config()).await.unwrap();mount_local(&stack, "/local", dir.path().to_str().unwrap()).await.unwrap();diff --git a/crates/ragfs/src/git/service.rs b/crates/ragfs/src/git/service.rsindex 52781e54d..47777654d 100644--- a/crates/ragfs/src/git/service.rs+++ b/crates/ragfs/src/git/service.rs@@ -6551,7 +6551,7 @@ mod fast_path1_tests {).unwrap();- let stack = build_default_stack(RagfsConfig::default()).await;+ let stack = build_default_stack(RagfsConfig::default()).await.unwrap();let mut params = HashMap::new();params.insert("local_dir".to_string(),diff --git a/crates/ragfs/src/lock/cache_provder.rs b/crates/ragfs/src/lock/cache_provder.rsnew file mode 100644index 000000000..29274ac98--- /dev/null+++ b/crates/ragfs/src/lock/cache_provder.rs@@ -0,0 +1,1869 @@+//! Redis-backed PathLock storage.++use std::sync::Arc;++use async_trait::async_trait;+use bytes::Bytes;++use crate::cache_runtime::{+ CacheError, CacheOperation, CacheRuntime, ScriptDefinition, ScriptRequest, ScriptValue,+};++use super::codec::LockTokenCodec;+use super::provider::{AcquisitionChange, AtomicAcquisition, PathLockHandleMode, PathLockProvider};+use super::types::{LockToken, PathLockError, PathLockKind, PathLockRequest, PathLockResult};++const ACQUIRE_BATCH_ID: &str = "pathlock.acquire_batch.v1";+const ROLLBACK_BATCH_ID: &str = "pathlock.rollback_batch.v1";+const COMPARE_WRITE_ID: &str = "pathlock.compare_write.v1";+const COMPARE_REMOVE_ID: &str = "pathlock.compare_remove.v1";+const REFRESH_ID: &str = "pathlock.refresh.v1";+const IS_LOCKED_ID: &str = "pathlock.is_locked.v1";+const SCAN_DESCENDANTS_ID: &str = "pathlock.scan_descendants.v1";+const READ_MANY_ID: &str = "pathlock.read_many.v1";+const CREATE_ID: &str = "pathlock.create.v1";++macro_rules! token_script {+ ($body:literal) => {+ concat!(+ r#"+local u128_max = "340282366920938463463374607431768211455"+local function normalize_decimal(value)+ if not value or not string.match(value, "^%d+$") then+ return nil+ end+ local normalized = string.gsub(value, "^0+", "")+ if normalized == "" then+ return "0"+ end+ if string.len(normalized) > string.len(u128_max)+ or (string.len(normalized) == string.len(u128_max)+ and normalized > u128_max) then+ return nil+ end+ return normalized+end++local function decimal_less(left, right)+ left = normalize_decimal(left)+ right = normalize_decimal(right)+ if not left or not right then+ return nil+ end+ if string.len(left) ~= string.len(right) then+ return string.len(left) < string.len(right)+ end+ return left < right+end+local function decode_token(raw)+ local p1 = string.find(raw, ":", 1, true)+ local p2 = p1 and string.find(raw, ":", p1 + 1, true)+ local p3 = p2 and string.find(raw, ":", p2 + 1, true)+ if not p1 or not p2 or p3 then+ return nil+ end+ local token_owner = string.sub(raw, 1, p1 - 1)+ local time_ns = string.sub(raw, p1 + 1, p2 - 1)+ local kind = string.sub(raw, p2 + 1)+ if token_owner == "" or not normalize_decimal(time_ns)+ or (kind ~= "E" and kind ~= "T") then+ return nil+ end+ return { owner = token_owner, time_ns = time_ns, kind = kind }+end+local function ancestors(path)+ local result = {}+ if path == "/" then+ return result+ end+ table.insert(result, "/")+ local start = 2+ while true do+ local slash = string.find(path, "/", start, true)+ if not slash then+ break+ end+ table.insert(result, string.sub(path, 1, slash - 1))+ start = slash + 1+ end+ return result+end+"#,+ $body+ )+ };+}++const ACQUIRE_BATCH_SCRIPT: &str = token_script!(+ r#"+local key = KEYS[1]+local owner = ARGV[1]+local now_ns = ARGV[2]+local stale_before_ns = ARGV[3]+local ttl_ms = tonumber(ARGV[4])+local function is_descendant(path, root)+ if root == "/" then+ return path ~= "/"+ end+ return string.sub(path, 1, string.len(root) + 1) == root .. "/"+end++if not owner or owner == "" or string.find(owner, ":", 1, true)+ or not normalize_decimal(now_ns) or not normalize_decimal(stale_before_ns)+ or not ttl_ms or ttl_ms <= 0 or (#ARGV - 4) % 2 ~= 0 or #ARGV == 4 then+ return { "invalid_request", "invalid acquire arguments" }+end++local requests = {}+local includes_tree = false+for index = 5, #ARGV, 2 do+ local path = ARGV[index]+ local kind = ARGV[index + 1]+ if not path or string.sub(path, 1, 1) ~= "/"+ or (path ~= "/" and string.sub(path, -1) == "/")+ or (kind ~= "E" and kind ~= "T") then+ return { "invalid_request", "invalid path or lock kind" }+ end+ table.insert(requests, { path = path, kind = kind })+ if kind == "T" then+ includes_tree = true+ end+end++local records = {}+if includes_tree then+ local values = redis.call("HGETALL", key)+ for index = 1, #values, 2 do+ local path = values[index]+ local raw = values[index + 1]+ local token = decode_token(raw)+ if not token then+ return { "invalid_token", path, raw }+ end+ records[path] = { raw = raw, token = token }+ end+else+ local fields = {}+ local seen = {}+ local function add_field(path)+ if not seen[path] then+ seen[path] = true+ table.insert(fields, path)+ end+ end+ for _, request in ipairs(requests) do+ add_field(request.path)+ for _, ancestor in ipairs(ancestors(request.path)) do+ add_field(ancestor)+ end+ end+ local values = redis.call("HMGET", key, unpack(fields))+ for index, raw in ipairs(values) do+ if raw then+ local token = decode_token(raw)+ if not token then+ return { "invalid_token", fields[index], raw }+ end+ records[fields[index]] = { raw = raw, token = token }+ end+ end+end++local stale = {}+local stale_seen = {}+local function is_other_stale(record)+ if not record or record.token.owner == owner then+ return false+ end+ return decimal_less(record.token.time_ns, stale_before_ns) == true+end+local function mark_stale(path, record)+ if is_other_stale(record) and not stale_seen[path] then+ stale_seen[path] = true+ table.insert(stale, path)+ end+end++for path, record in pairs(records) do+ mark_stale(path, record)+end++for _, request in ipairs(requests) do+ local target = records[request.path]+ if target and target.token.owner ~= owner and not is_other_stale(target) then+ return { "conflict", request.path, target.raw }+ end+ for _, ancestor in ipairs(ancestors(request.path)) do+ local record = records[ancestor]+ if record and record.token.owner ~= owner and record.token.kind == "T"+ and not is_other_stale(record) then+ return { "conflict", ancestor, record.raw }+ end+ end+ if request.kind == "T" then+ for path, record in pairs(records) do+ if is_descendant(path, request.path)+ and record.token.owner ~= owner and not is_other_stale(record) then+ return { "conflict", path, record.raw }+ end+ end+ end+end++local changes = {}+for _, request in ipairs(requests) do+ local existing = records[request.path]+ local replacement = owner .. ":" .. now_ns .. ":" .. request.kind+ if existing and existing.token.owner == owner then+ if request.kind == "T" and existing.token.kind == "E" then+ table.insert(changes, {+ path = request.path,+ change = "upgraded",+ previous = existing.raw,+ replacement = replacement,+ })+ else+ table.insert(changes, {+ path = request.path,+ change = "reentrant",+ previous = "",+ replacement = "",+ })+ end+ else+ table.insert(changes, {+ path = request.path,+ change = "created",+ previous = "",+ replacement = replacement,+ })+ end+end++local stale_batch_size = 1000+for start_index = 1, #stale, stale_batch_size do+ local end_index = math.min(start_index + stale_batch_size - 1, #stale)+ redis.call("HDEL", key, unpack(stale, start_index, end_index))+end+for _, change in ipairs(changes) do+ if change.change ~= "reentrant" then+ redis.call("HSET", key, change.path, change.replacement)+ end+end+if redis.call("HLEN", key) > 0 then+ redis.call("PEXPIRE", key, ttl_ms)+end++local result = { "ok" }+for _, change in ipairs(changes) do+ table.insert(result, change.path)+ table.insert(result, change.change)+ table.insert(result, change.previous)+ table.insert(result, change.replacement)+end+return result+"#+);++const ROLLBACK_BATCH_SCRIPT: &str = r#"+local key = KEYS[1]+local owner = ARGV[1]+local ttl_ms = tonumber(ARGV[2])+if not owner or owner == "" or not ttl_ms or ttl_ms <= 0+ or (#ARGV - 2) % 4 ~= 0 then+ return { "invalid_request", "invalid rollback arguments" }+end++local changes = {}+for index = 3, #ARGV, 4 do+ local path = ARGV[index]+ local change = ARGV[index + 1]+ local previous = ARGV[index + 2]+ local replacement = ARGV[index + 3]+ if change ~= "created" and change ~= "reentrant" and change ~= "upgraded" then+ return { "invalid_request", "invalid acquisition change" }+ end+ if change ~= "reentrant" then+ local current = redis.call("HGET", key, path)+ if current ~= replacement then+ return { "changed", path }+ end+ if string.sub(replacement, 1, string.len(owner) + 1) ~= owner .. ":" then+ return { "invalid_request", "replacement owner mismatch" }+ end+ end+ table.insert(changes, {+ path = path,+ change = change,+ previous = previous,+ })+end++for index = #changes, 1, -1 do+ local change = changes[index]+ if change.change == "created" then+ redis.call("HDEL", key, change.path)+ elseif change.change == "upgraded" then+ redis.call("HSET", key, change.path, change.previous)+ end+end+if redis.call("HLEN", key) > 0 then+ redis.call("PEXPIRE", key, ttl_ms)+end+return { "ok" }+"#;++const COMPARE_WRITE_SCRIPT: &str = r#"+local current = redis.call("HGET", KEYS[1], ARGV[1])+if current ~= ARGV[2] then+ return 0+end+redis.call("HSET", KEYS[1], ARGV[1], ARGV[3])+redis.call("PEXPIRE", KEYS[1], ARGV[4])+return 1+"#;++const COMPARE_REMOVE_SCRIPT: &str = r#"+local current = redis.call("HGET", KEYS[1], ARGV[1])+if current ~= ARGV[2] then+ return 0+end+redis.call("HDEL", KEYS[1], ARGV[1])+if redis.call("HLEN", KEYS[1]) > 0 then+ redis.call("PEXPIRE", KEYS[1], ARGV[3])+end+return 1+"#;++const REFRESH_SCRIPT: &str = token_script!(+ r#"+local raw = redis.call("HGET", KEYS[1], ARGV[1])+if not raw then+ return { "missing" }+end+local token = decode_token(raw)+if not token then+ return { "invalid_token", raw }+end+if token.owner ~= ARGV[2] then+ return { "owner_mismatch" }+end+if not normalize_decimal(ARGV[3]) then+ return { "invalid_request", "invalid time_ns" }+end+redis.call("HSET", KEYS[1], ARGV[1], token.owner .. ":" .. ARGV[3] .. ":" .. token.kind)+redis.call("PEXPIRE", KEYS[1], ARGV[4])+return { "ok" }+"#+);++const IS_LOCKED_SCRIPT: &str = token_script!(+ r#"+local path = ARGV[1]+local stale_before_ns = ARGV[2]+local ignore_stale = ARGV[3] == "1"++local fields = { path }+for _, ancestor in ipairs(ancestors(path)) do+ table.insert(fields, ancestor)+end+local values = redis.call("HMGET", KEYS[1], unpack(fields))+for index, raw in ipairs(values) do+ if raw then+ local token = decode_token(raw)+ if not token then+ return { "invalid_token", fields[index], raw }+ end+ local live = not ignore_stale+ or decimal_less(token.time_ns, stale_before_ns) ~= true+ if live and (index == 1 or token.kind == "T") then+ return { "ok", 1 }+ end+ end+end+return { "ok", 0 }+"#+);++const SCAN_DESCENDANTS_SCRIPT: &str = r#"+local root = ARGV[1]+local values = redis.call("HGETALL", KEYS[1])+local result = { "ok" }+for index = 1, #values, 2 do+ local path = values[index]+ local matches = root == "/" or path == root+ or string.sub(path, 1, string.len(root) + 1) == root .. "/"+ if matches then+ table.insert(result, path)+ table.insert(result, values[index + 1])+ end+end+return result+"#;++const READ_MANY_SCRIPT: &str = r#"+if #ARGV == 0 then+ return {}+end+return redis.call("HMGET", KEYS[1], unpack(ARGV))+"#;++const CREATE_SCRIPT: &str = r#"+local current = redis.call("HGET", KEYS[1], ARGV[1])+if current then+ return { "exists", current }+end+redis.call("HSET", KEYS[1], ARGV[1], ARGV[2])+redis.call("PEXPIRE", KEYS[1], ARGV[3])+return { "created" }+"#;++macro_rules! script {+ ($id:expr, $lua:expr) => {+ ScriptDefinition {+ id: $id,+ redis_lua: $lua,+ }+ };+}++const SCRIPT_DEFINITIONS: &[ScriptDefinition] = &[+ script!(ACQUIRE_BATCH_ID, ACQUIRE_BATCH_SCRIPT),+ script!(ROLLBACK_BATCH_ID, ROLLBACK_BATCH_SCRIPT),+ script!(COMPARE_WRITE_ID, COMPARE_WRITE_SCRIPT),+ script!(COMPARE_REMOVE_ID, COMPARE_REMOVE_SCRIPT),+ script!(REFRESH_ID, REFRESH_SCRIPT),+ script!(IS_LOCKED_ID, IS_LOCKED_SCRIPT),+ script!(SCAN_DESCENDANTS_ID, SCAN_DESCENDANTS_SCRIPT),+ script!(READ_MANY_ID, READ_MANY_SCRIPT),+ script!(CREATE_ID, CREATE_SCRIPT),+];++/// Redis-backed PathLock provider.+pub struct RedisPathLockProvider {+ runtime: Arc<CacheRuntime>,+ namespace: String,+ hash_ttl_ms: i64,+}++impl RedisPathLockProvider {+ /// Create Redis-backed PathLock storage and register its Lua scripts.+ pub fn new(+ runtime: Arc<CacheRuntime>,+ namespace: &str,+ lock_expire_secs: f64,+ ) -> PathLockResult<Self> {+ if namespace.is_empty()+ || !namespace+ .bytes()+ .all(|byte| byte.is_ascii_alphanumeric() || matches!(byte, b'.' | b'_' | b'-'))+ {+ return Err(PathLockError::InvalidRequest(+ "pathlock Redis namespace must contain only ASCII letters, digits, '.', '_' or '-'"+ .to_string(),+ ));+ }+ if !lock_expire_secs.is_finite() || lock_expire_secs < 1.0 {+ return Err(PathLockError::InvalidRequest(+ "pathlock lock_expire_secs must be finite and >= 1.0".to_string(),+ ));+ }+ let hash_ttl_ms = (lock_expire_secs * 2_000.0).ceil();+ if hash_ttl_ms > i64::MAX as f64 {+ return Err(PathLockError::InvalidRequest(+ "pathlock Redis HASH TTL exceeds i64 milliseconds".to_string(),+ ));+ }+ runtime+ .require_operations(&[CacheOperation::ExecuteScript])+ .map_err(Self::cache_error)?;+ for definition in SCRIPT_DEFINITIONS {+ runtime+ .register_script(*definition)+ .map_err(Self::cache_error)?;+ }+ Ok(Self {+ runtime,+ namespace: namespace.to_string(),+ hash_ttl_ms: hash_ttl_ms as i64,+ })+ }++ /// Return the Redis HASH key responsible for one logical path.+ fn tokens_key_for_path(&self, path: &str) -> PathLockResult<String> {+ let suffix = if path == "/" || path == "/local" {+ "global".to_string()+ } else {+ let scope = path+ .strip_prefix("/local/")+ .and_then(|path| path.split('/').next())+ .filter(|scope| !scope.is_empty())+ .ok_or_else(|| {+ PathLockError::InvalidRequest(format!(+ "cache PathLock path must be '/' or below '/local': {path}"+ ))+ })?;+ match scope {+ "_system" => "scope:_system".to_string(),+ account => format!("scope:account:{account}"),+ }+ };+ Ok(format!(+ "ov:pathlock:{{{}}}:{suffix}:tokens",+ self.namespace+ ))+ }++ /// Return the shared Redis HASH key for one same-scope path batch.+ fn tokens_key_for_batch<'a>(+ &self,+ paths: impl IntoIterator<Item = &'a str>,+ ) -> PathLockResult<String> {+ let mut paths = paths.into_iter();+ let first_path = paths.next().ok_or_else(|| {+ PathLockError::InvalidRequest("lock request batch must not be empty".to_string())+ })?;+ let key = self.tokens_key_for_path(first_path)?;+ for path in paths {+ if self.tokens_key_for_path(path)? != key {+ return Err(PathLockError::InvalidRequest(+ "cache PathLock batch paths must belong to one scope".to_string(),+ ));+ }+ }+ Ok(key)+ }++ /// Execute one registered PathLock script and decode its provider-neutral result.+ async fn execute(+ &self,+ script_id: &str,+ key: String,+ args: Vec<Bytes>,+ ) -> PathLockResult<ScriptValue> {+ self.runtime+ .execute_script(ScriptRequest {+ script_id: script_id.to_string(),+ keys: vec![key],+ args,+ })+ .await+ .and_then(|result| result.decode())+ .map_err(Self::cache_error)+ }++ /// Execute one script and require an array result.+ async fn execute_array(+ &self,+ script_id: &str,+ key: String,+ args: Vec<Bytes>,+ ) -> PathLockResult<Vec<ScriptValue>> {+ match self.execute(script_id, key, args).await? {+ ScriptValue::Array(values) => Ok(values),+ other => Err(PathLockError::Internal(format!(+ "Redis PathLock {script_id} returned non-array result: {other:?}"+ ))),+ }+ }++ /// Execute one script and require an integer result.+ async fn execute_integer(+ &self,+ script_id: &str,+ key: String,+ args: Vec<Bytes>,+ ) -> PathLockResult<i64> {+ match self.execute(script_id, key, args).await? {+ ScriptValue::Integer(value) => Ok(value),+ other => Err(PathLockError::Internal(format!(+ "Redis PathLock {script_id} returned non-integer result: {other:?}"+ ))),+ }+ }++ /// Convert one cache runtime error into a PathLock I/O error.+ fn cache_error(error: CacheError) -> PathLockError {+ PathLockError::Io(format!("Redis PathLock operation failed: {error}"))+ }++ /// Decode one script value as UTF-8 text.+ fn result_string<'a>(value: &'a ScriptValue, operation: &str) -> PathLockResult<&'a str> {+ match value {+ ScriptValue::Bytes(value) => std::str::from_utf8(value).map_err(|error| {+ PathLockError::Internal(format!(+ "Redis PathLock {operation} returned invalid UTF-8: {error}"+ ))+ }),+ other => Err(PathLockError::Internal(format!(+ "Redis PathLock {operation} returned non-string value: {other:?}"+ ))),+ }+ }++ /// Return the leading status string from one script array.+ fn result_status<'a>(values: &'a [ScriptValue], operation: &str) -> PathLockResult<&'a str> {+ values+ .first()+ .ok_or_else(|| {+ PathLockError::Internal(format!(+ "Redis PathLock {operation} returned an empty result"+ ))+ })+ .and_then(|value| Self::result_string(value, operation))+ }++ /// Decode one raw Redis token and include its path in decoding errors.+ fn decode_token(path: &str, raw: &str) -> PathLockResult<LockToken> {+ LockTokenCodec::decode(raw)+ .map_err(|_| PathLockError::InvalidToken(format!("invalid token at '{path}': {raw}")))+ }++ /// Decode a conflict or invalid-token script response.+ fn decode_error_result(+ operation: &str,+ values: &[ScriptValue],+ ) -> PathLockResult<PathLockError> {+ let status = Self::result_status(values, operation)?;+ match status {+ "conflict" if values.len() == 3 => {+ let path = Self::result_string(&values[1], operation)?;+ let raw = Self::result_string(&values[2], operation)?;+ let token = Self::decode_token(path, raw)?;+ Ok(PathLockError::Conflict {+ lock_path: path.to_string(),+ owner: token.owner_id,+ kind: token.lock_type,+ })+ }+ "invalid_token" if values.len() == 3 => {+ let path = Self::result_string(&values[1], operation)?;+ let raw = Self::result_string(&values[2], operation)?;+ Ok(PathLockError::InvalidToken(format!(+ "invalid token at '{path}': {raw}"+ )))+ }+ "invalid_request" if values.len() == 2 => Ok(PathLockError::InvalidRequest(+ Self::result_string(&values[1], operation)?.to_string(),+ )),+ "changed" if values.len() == 2 => Ok(PathLockError::Io(format!(+ "Redis PathLock rollback value changed at '{}'",+ Self::result_string(&values[1], operation)?+ ))),+ _ => Ok(PathLockError::Internal(format!(+ "Redis PathLock {operation} returned invalid status '{status}'"+ ))),+ }+ }++ /// Encode one string-like script argument.+ fn bytes(value: impl AsRef<[u8]>) -> Bytes {+ Bytes::copy_from_slice(value.as_ref())+ }++ /// Return the string code used by Redis for one lock kind.+ fn kind_code(kind: PathLockKind) -> &'static str {+ match kind {+ PathLockKind::Exact => "E",+ PathLockKind::Tree => "T",+ }+ }++ /// Read and decode multiple token fields while preserving input order.+ async fn read_many_tokens(&self, paths: &[String]) -> PathLockResult<Vec<Option<LockToken>>> {+ if paths.is_empty() {+ return Ok(Vec::new());+ }+ let key = self.tokens_key_for_batch(paths.iter().map(String::as_str))?;+ let values = self+ .execute_array(+ READ_MANY_ID,+ key,+ paths.iter().map(Self::bytes).collect::<Vec<_>>(),+ )+ .await?;+ if values.len() != paths.len() {+ return Err(PathLockError::Internal(format!(+ "Redis PathLock read_many returned {} values for {} paths",+ values.len(),+ paths.len()+ )));+ }+ values+ .iter()+ .zip(paths)+ .map(|(value, path)| match value {+ ScriptValue::Null => Ok(None),+ ScriptValue::Bytes(raw) => {+ let raw = std::str::from_utf8(raw).map_err(|error| {+ PathLockError::InvalidToken(format!(+ "invalid UTF-8 token at '{path}': {error}"+ ))+ })?;+ Self::decode_token(path, raw).map(Some)+ }+ other => Err(PathLockError::Internal(format!(+ "Redis PathLock read_many returned invalid value for '{path}': {other:?}"+ ))),+ })+ .collect()+ }+}++#[async_trait]+impl PathLockProvider for RedisPathLockProvider {+ /// Return the provider name used by configuration and diagnostics.+ fn name(&self) -> &'static str {+ "cache"+ }++ /// Return logical paths because Redis HASH fields are business paths.+ fn handle_mode(&self) -> PathLockHandleMode {+ PathLockHandleMode::LogicalPath+ }++ /// Atomically check conflicts and acquire one normalized request batch.+ async fn try_acquire_batch_atomic(+ &self,+ requests: &[PathLockRequest],+ owner_id: &str,+ now_ns: u128,+ stale_before_ns: u128,+ ) -> PathLockResult<Option<Vec<AtomicAcquisition>>> {+ if requests.is_empty() {+ return Err(PathLockError::InvalidRequest(+ "lock request batch must not be empty".to_string(),+ ));+ }+ let key =+ self.tokens_key_for_batch(requests.iter().map(|request| request.path.as_str()))?;+ let mut args = vec![+ Self::bytes(owner_id),+ Self::bytes(now_ns.to_string()),+ Self::bytes(stale_before_ns.to_string()),+ Self::bytes(self.hash_ttl_ms.to_string()),+ ];+ for request in requests {+ args.push(Self::bytes(&request.path));+ args.push(Self::bytes(Self::kind_code(request.kind)));+ }+ let values = self.execute_array(ACQUIRE_BATCH_ID, key, args).await?;+ let status = Self::result_status(&values, "acquire_batch")?;+ if status != "ok" {+ return Err(Self::decode_error_result("acquire_batch", &values)?);+ }+ if (values.len() - 1) % 4 != 0 {+ return Err(PathLockError::Internal(format!(+ "Redis PathLock acquire_batch returned {} trailing values",+ values.len() - 1+ )));+ }++ let mut acquisitions = Vec::with_capacity((values.len() - 1) / 4);+ for values in values[1..].chunks_exact(4) {+ let handle = Self::result_string(&values[0], "acquire_batch")?.to_string();+ let change = Self::result_string(&values[1], "acquire_batch")?;+ let previous = Self::result_string(&values[2], "acquire_batch")?;+ let replacement = Self::result_string(&values[3], "acquire_batch")?;+ let change = match change {+ "created" => AcquisitionChange::Created {+ replacement: Self::decode_token(&handle, replacement)?,+ },+ "reentrant" => AcquisitionChange::Reentrant,+ "upgraded" => AcquisitionChange::Upgraded {+ previous: Self::decode_token(&handle, previous)?,+ replacement: Self::decode_token(&handle, replacement)?,+ },+ other => {+ return Err(PathLockError::Internal(format!(+ "Redis PathLock acquire_batch returned unknown change '{other}'"+ )));+ }+ };+ acquisitions.push(AtomicAcquisition { handle, change });+ }+ Ok(Some(acquisitions))+ }++ /// Atomically roll back mutations reported by one completed batch.+ async fn rollback_acquisitions_atomic(+ &self,+ acquisitions: &[AtomicAcquisition],+ owner_id: &str,+ ) -> PathLockResult<Option<()>> {+ if acquisitions.is_empty() {+ return Ok(Some(()));+ }+ let key =+ self.tokens_key_for_batch(acquisitions.iter().map(|item| item.handle.as_str()))?;+ let mut args = vec![+ Self::bytes(owner_id),+ Self::bytes(self.hash_ttl_ms.to_string()),+ ];+ for acquisition in acquisitions {+ args.push(Self::bytes(&acquisition.handle));+ match &acquisition.change {+ AcquisitionChange::Created { replacement } => {+ args.push(Self::bytes("created"));+ args.push(Self::bytes(""));+ args.push(Self::bytes(LockTokenCodec::encode(replacement)));+ }+ AcquisitionChange::Reentrant => {+ args.push(Self::bytes("reentrant"));+ args.push(Self::bytes(""));+ args.push(Self::bytes(""));+ }+ AcquisitionChange::Upgraded {+ previous,+ replacement,+ } => {+ args.push(Self::bytes("upgraded"));+ args.push(Self::bytes(LockTokenCodec::encode(previous)));+ args.push(Self::bytes(LockTokenCodec::encode(replacement)));+ }+ }+ }+ let values = self.execute_array(ROLLBACK_BATCH_ID, key, args).await?;+ let status = Self::result_status(&values, "rollback_batch")?;+ if status == "ok" && values.len() == 1 {+ return Ok(Some(()));+ }+ Err(Self::decode_error_result("rollback_batch", &values)?)+ }++ /// Check whether a logical path is covered by a matching live token.+ async fn is_path_locked_atomic(+ &self,+ path: &str,+ _now_ns: u128,+ stale_before_ns: u128,+ ignore_stale: bool,+ ) -> PathLockResult<Option<bool>> {+ let key = self.tokens_key_for_path(path)?;+ let values = self+ .execute_array(+ IS_LOCKED_ID,+ key,+ vec![+ Self::bytes(path),+ Self::bytes(stale_before_ns.to_string()),+ Self::bytes(if ignore_stale { "1" } else { "0" }),+ ],+ )+ .await?;+ let status = Self::result_status(&values, "is_locked")?;+ if status != "ok" {+ return Err(Self::decode_error_result("is_locked", &values)?);+ }+ if values.len() != 2 {+ return Err(PathLockError::Internal(format!(+ "Redis PathLock is_locked returned {} values",+ values.len()+ )));+ }+ match values[1] {+ ScriptValue::Integer(value) => Ok(Some(value != 0)),+ ref other => Err(PathLockError::Internal(format!(+ "Redis PathLock is_locked returned non-integer value: {other:?}"+ ))),+ }+ }++ /// Read and decode one logical path token.+ async fn read_token(&self, lock_path: &str) -> PathLockResult<Option<LockToken>> {+ self.read_many_tokens(&[lock_path.to_string()])+ .await+ .map(|mut values| values.pop().flatten())+ }++ /// Atomically create one token when the path is absent.+ async fn try_create_token(&self, lock_path: &str, token: &LockToken) -> PathLockResult<()> {+ let key = self.tokens_key_for_path(lock_path)?;+ let values = self+ .execute_array(+ CREATE_ID,+ key,+ vec![+ Self::bytes(lock_path),+ Self::bytes(LockTokenCodec::encode(token)),+ Self::bytes(self.hash_ttl_ms.to_string()),+ ],+ )+ .await?;+ let status = Self::result_status(&values, "create")?;+ match status {+ "created" if values.len() == 1 => Ok(()),+ "exists" if values.len() == 2 => {+ let raw = Self::result_string(&values[1], "create")?;+ let current = Self::decode_token(lock_path, raw)?;+ Err(PathLockError::Conflict {+ lock_path: lock_path.to_string(),+ owner: current.owner_id,+ kind: current.lock_type,+ })+ }+ _ => Err(PathLockError::Internal(format!(+ "Redis PathLock create returned invalid status '{status}'"+ ))),+ }+ }++ /// Replace one token only when its complete encoded value still matches.+ async fn compare_and_write_token(+ &self,+ lock_path: &str,+ expected: &LockToken,+ replacement: &LockToken,+ ) -> PathLockResult<bool> {+ let key = self.tokens_key_for_path(lock_path)?;+ self.execute_integer(+ COMPARE_WRITE_ID,+ key,+ vec![+ Self::bytes(lock_path),+ Self::bytes(LockTokenCodec::encode(expected)),+ Self::bytes(LockTokenCodec::encode(replacement)),+ Self::bytes(self.hash_ttl_ms.to_string()),+ ],+ )+ .await+ .map(|value| value != 0)+ }++ /// Refresh one owned token while preserving its lock kind.+ async fn refresh_token(+ &self,+ lock_path: &str,+ owner_id: &str,+ time_ns: u128,+ ) -> PathLockResult<bool> {+ let key = self.tokens_key_for_path(lock_path)?;+ let values = self+ .execute_array(+ REFRESH_ID,+ key,+ vec![+ Self::bytes(lock_path),+ Self::bytes(owner_id),+ Self::bytes(time_ns.to_string()),+ Self::bytes(self.hash_ttl_ms.to_string()),+ ],+ )+ .await?;+ let status = Self::result_status(&values, "refresh")?;+ match status {+ "ok" if values.len() == 1 => Ok(true),+ "missing" | "owner_mismatch" if values.len() == 1 => Ok(false),+ "invalid_token" if values.len() == 2 => Err(PathLockError::InvalidToken(format!(+ "invalid token at '{lock_path}': {}",+ Self::result_string(&values[1], "refresh")?+ ))),+ "invalid_request" if values.len() == 2 => Err(PathLockError::InvalidRequest(+ Self::result_string(&values[1], "refresh")?.to_string(),+ )),+ _ => Err(PathLockError::Internal(format!(+ "Redis PathLock refresh returned invalid status '{status}'"+ ))),+ }+ }++ /// Remove one owned token using complete-token compare-and-remove.+ async fn remove_token(+ &self,+ lock_path: &str,+ owner_id: &str,+ _force: bool,+ ) -> PathLockResult<bool> {+ let Some(current) = self.read_token(lock_path).await? else {+ return Ok(false);+ };+ if current.owner_id != owner_id {+ return Ok(false);+ }+ let key = self.tokens_key_for_path(lock_path)?;+ self.execute_integer(+ COMPARE_REMOVE_ID,+ key,+ vec![+ Self::bytes(lock_path),+ Self::bytes(LockTokenCodec::encode(¤t)),+ Self::bytes(self.hash_ttl_ms.to_string()),+ ],+ )+ .await+ .map(|value| value != 0)+ }++ /// Return logical paths equal to or below one root.+ async fn scan_descendant_locks(&self, root: &str) -> PathLockResult<Vec<String>> {+ let key = self.tokens_key_for_path(root)?;+ let values = self+ .execute_array(SCAN_DESCENDANTS_ID, key, vec![Self::bytes(root)])+ .await?;+ let status = Self::result_status(&values, "scan_descendants")?;+ if status != "ok" {+ return Err(Self::decode_error_result("scan_descendants", &values)?);+ }+ if (values.len() - 1) % 2 != 0 {+ return Err(PathLockError::Internal(format!(+ "Redis PathLock scan_descendants returned {} trailing values",+ values.len() - 1+ )));+ }+ let mut paths = Vec::with_capacity((values.len() - 1) / 2);+ for values in values[1..].chunks_exact(2) {+ let path = Self::result_string(&values[0], "scan_descendants")?;+ let raw = Self::result_string(&values[1], "scan_descendants")?;+ Self::decode_token(path, raw)?;+ paths.push(path.to_string());+ }+ Ok(paths)+ }+}++#[cfg(test)]+mod tests {+ use std::sync::atomic::{AtomicUsize, Ordering};+ use std::sync::Arc;+ use std::time::{Duration, Instant};++ use crate::cache_runtime::{+ CacheRuntime, RedisProviderConfig, ScriptDefinition, ScriptRequest, ScriptValue,+ };+ use crate::plugins::memfs::MemFileSystem;++ use super::super::manager::{PathLockConfig, PathLockManager};+ use super::super::provider::{+ AcquisitionChange, AtomicAcquisition, PathLockHandleMode, PathLockProvider,+ };+ use super::super::types::{+ LockToken, PathLockError, PathLockHandoffRef, PathLockKind, PathLockRequest,+ };+ use super::*;++ const TEST_PTTL_ID: &str = "pathlock.test.pttl.v1";+ const TEST_PTTL_SCRIPT: &str = "return redis.call('PTTL', KEYS[1])";+ const TEST_HASH_ID: &str = "pathlock.test.hash.v1";+ const TEST_HASH_SCRIPT: &str = r#"+if ARGV[1] == "set" then+ redis.call("HSET", KEYS[1], ARGV[2], ARGV[3])+ return ARGV[3]+end+return redis.call("HGET", KEYS[1], ARGV[2])+"#;++ enum AtomicFault {+ WriteThenIo,+ Conflict,+ }++ /// Logical test provider for atomic Manager failure paths.+ struct FaultProvider {+ inner: super::super::provider::MemoryPathLockProvider,+ fault: AtomicFault,+ remove_calls: AtomicUsize,+ }++ impl FaultProvider {+ /// Create one provider with the selected injected fault.+ fn new(fault: AtomicFault) -> Self {+ Self {+ inner: super::super::provider::MemoryPathLockProvider::new(),+ fault,+ remove_calls: AtomicUsize::new(0),+ }+ }+ }++ #[async_trait]+ impl PathLockProvider for FaultProvider {+ /// Return the provider name used by test diagnostics.+ fn name(&self) -> &'static str {+ "fault"+ }++ /// Return logical handles to exercise the atomic Manager branch.+ fn handle_mode(&self) -> PathLockHandleMode {+ PathLockHandleMode::LogicalPath+ }++ /// Inject either an unknown write result or a conflict.+ async fn try_acquire_batch_atomic(+ &self,+ requests: &[PathLockRequest],+ owner_id: &str,+ now_ns: u128,+ _stale_before_ns: u128,+ ) -> PathLockResult<Option<Vec<AtomicAcquisition>>> {+ match self.fault {+ AtomicFault::WriteThenIo => {+ let request = &requests[0];+ self.inner+ .try_create_token(&request.path, &token(owner_id, now_ns, request.kind))+ .await?;+ Err(PathLockError::Io(+ "simulated response timeout after write".to_string(),+ ))+ }+ AtomicFault::Conflict => Err(PathLockError::Conflict {+ lock_path: "/race".to_string(),+ owner: "owner-a".to_string(),+ kind: PathLockKind::Exact,+ }),+ }+ }++ /// Return stored data or the stale conflict snapshot.+ async fn read_token(&self, lock_path: &str) -> PathLockResult<Option<LockToken>> {+ match self.fault {+ AtomicFault::Conflict => Ok(Some(token("owner-a", 1, PathLockKind::Exact))),+ AtomicFault::WriteThenIo => self.inner.read_token(lock_path).await,+ }+ }++ /// Delegate fallback token creation to memory storage.+ async fn try_create_token(&self, lock_path: &str, token: &LockToken) -> PathLockResult<()> {+ self.inner.try_create_token(lock_path, token).await+ }++ /// Delegate fallback token replacement to memory storage.+ 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+ }++ /// Delegate refresh to memory storage.+ 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+ }++ /// Record cleanup calls and delegate removal.+ async fn remove_token(+ &self,+ lock_path: &str,+ owner_id: &str,+ force: bool,+ ) -> PathLockResult<bool> {+ self.remove_calls.fetch_add(1, Ordering::SeqCst);+ self.inner.remove_token(lock_path, owner_id, force).await+ }++ /// Delegate descendant scans to memory storage.+ async fn scan_descendant_locks(&self, root: &str) -> PathLockResult<Vec<String>> {+ self.inner.scan_descendant_locks(root).await+ }+ }++ /// Build a real Redis provider when the integration endpoint is configured.+ async fn test_provider(test_name: &str) -> Option<(Arc<CacheRuntime>, RedisPathLockProvider)> {+ let endpoint = std::env::var("REDIS_URL").ok()?;+ let runtime = CacheRuntime::redis(RedisProviderConfig {+ endpoints: vec![endpoint],+ command_timeout_ms: 1_000,+ ..RedisProviderConfig::default()+ })+ .await+ .unwrap();+ let namespace = format!("pathlock-test-{}-{test_name}", std::process::id());+ let provider = RedisPathLockProvider::new(runtime.clone(), &namespace, 1.0).unwrap();+ Some((runtime, provider))+ }++ /// Build two managers that share one Redis namespace.+ async fn test_managers(+ test_name: &str,+ ) -> Option<(Arc<CacheRuntime>, PathLockManager, PathLockManager, String)> {+ let endpoint = std::env::var("REDIS_URL").ok()?;+ let runtime = CacheRuntime::redis(RedisProviderConfig {+ endpoints: vec![endpoint],+ command_timeout_ms: 1_000,+ ..RedisProviderConfig::default()+ })+ .await+ .unwrap();+ let namespace = format!("pathlock-manager-test-{}-{test_name}", std::process::id());+ let config = PathLockConfig {+ provider: "cache".to_string(),+ namespace: Some(namespace.clone()),+ lock_timeout_secs: 0.0,+ lock_expire_secs: 3.0,+ };+ let first_provider =+ Arc::new(RedisPathLockProvider::new(runtime.clone(), &namespace, 3.0).unwrap());+ let key = first_provider+ .tokens_key_for_path("/local/account-a")+ .unwrap();+ let first = PathLockManager::new(+ Arc::new(MemFileSystem::new()),+ first_provider,+ config.clone(),+ );+ let second = PathLockManager::new(+ Arc::new(MemFileSystem::new()),+ Arc::new(RedisPathLockProvider::new(runtime.clone(), &namespace, 3.0).unwrap()),+ config,+ );+ Some((runtime, first, second, key))+ }++ /// Read a comma-separated Redis endpoint environment variable.+ fn topology_endpoints(variable: &str) -> Option<Vec<String>> {+ let endpoints = std::env::var(variable).ok()?;+ let endpoints = endpoints+ .split(',')+ .map(str::trim)+ .filter(|endpoint| !endpoint.is_empty())+ .map(str::to_string)+ .collect::<Vec<_>>();+ (!endpoints.is_empty()).then_some(endpoints)+ }++ /// Exercise one provider against a configured Redis topology.+ async fn exercise_topology(+ mode: &str,+ endpoints: Vec<String>,+ master_name: Option<String>,+ test_name: &str,+ ) {+ let runtime = CacheRuntime::redis(RedisProviderConfig {+ mode: mode.to_string(),+ endpoints,+ master_name,+ connect_timeout_ms: 10_000,+ command_timeout_ms: 3_000,+ ..RedisProviderConfig::default()+ })+ .await+ .unwrap();+ let namespace = format!("pathlock-topology-test-{}-{test_name}", std::process::id());+ let provider = RedisPathLockProvider::new(runtime.clone(), &namespace, 3.0).unwrap();++ provider+ .try_acquire_batch_atomic(+ &[request("/local/account-a/root", PathLockKind::Tree)],+ "owner-a",+ 100,+ 0,+ )+ .await+ .unwrap();+ assert!(matches!(+ provider+ .try_acquire_batch_atomic(+ &[request("/local/account-a/root/child", PathLockKind::Exact)],+ "owner-b",+ 101,+ 0,+ )+ .await,+ Err(PathLockError::Conflict { .. })+ ));++ runtime.close().await.unwrap();+ }++ /// Build one lock token for provider tests.+ fn token(owner_id: &str, time_ns: u128, lock_type: PathLockKind) -> LockToken {+ LockToken {+ owner_id: owner_id.to_string(),+ time_ns,+ lock_type,+ }+ }++ /// Build one logical lock request.+ fn request(path: &str, kind: PathLockKind) -> PathLockRequest {+ PathLockRequest {+ path: path.to_string(),+ kind,+ }+ }++ /// Verify invalid namespace and expiry values are rejected before Redis access.+ #[test]+ fn provider_rejects_invalid_configuration() {+ let runtime = CacheRuntime::memory();++ assert!(matches!(+ RedisPathLockProvider::new(runtime.clone(), "bad{name}", 1.0),+ Err(PathLockError::InvalidRequest(_))+ ));+ assert!(matches!(+ RedisPathLockProvider::new(runtime, "prod-a", f64::NAN),+ Err(PathLockError::InvalidRequest(_))+ ));+ }++ /// Verify global, system, and account paths use separate Redis HASH keys.+ #[tokio::test]+ async fn provider_routes_tokens_to_scope_hashes() {+ let Some((runtime, provider)) = test_provider("scope-keys").await else {+ return;+ };+ runtime+ .register_script(ScriptDefinition {+ id: TEST_HASH_ID,+ redis_lua: TEST_HASH_SCRIPT,+ })+ .unwrap();++ let cases = [+ ("/", "global"),+ ("/local", "global"),+ ("/local/_system/tasks/task.json", "scope:_system"),+ ("/local/account-a/resources/a.md", "scope:account:account-a"),+ ("/local/account-b/resources/b.md", "scope:account:account-b"),+ ];+ let namespace = format!("pathlock-test-{}-scope-keys", std::process::id());+ for (index, (path, scope)) in cases.iter().enumerate() {+ provider+ .try_create_token(+ path,+ &token("owner-a", index as u128 + 1, PathLockKind::Exact),+ )+ .await+ .unwrap();+ let raw = runtime+ .execute_script(ScriptRequest {+ script_id: TEST_HASH_ID.to_string(),+ keys: vec![format!("ov:pathlock:{{{namespace}}}:{scope}:tokens")],+ args: vec![+ RedisPathLockProvider::bytes("get"),+ RedisPathLockProvider::bytes(path),+ ],+ })+ .await+ .unwrap()+ .decode()+ .unwrap();+ assert!(matches!(raw, ScriptValue::Bytes(_)), "{path} missing");+ }+ assert!(matches!(+ provider+ .try_acquire_batch_atomic(+ &[+ request("/local/account-a/a", PathLockKind::Exact),+ request("/local/account-b/b", PathLockKind::Exact),+ ],+ "owner-a",+ 10,+ 0,+ )+ .await,+ Err(PathLockError::InvalidRequest(_))+ ));+ assert!(matches!(+ provider+ .try_create_token("/queue", &token("owner-a", 10, PathLockKind::Exact))+ .await,+ Err(PathLockError::InvalidRequest(_))+ ));++ runtime.close().await.unwrap();+ }++ /// Verify CRUD preserves the token format and refreshes the HASH TTL.+ #[tokio::test]+ async fn provider_crud_preserves_tokens_and_hash_ttl() {+ let Some((runtime, provider)) = test_provider("crud").await else {+ return;+ };+ let path = "/local/account-a/a";+ let original = token("owner-a", 100, PathLockKind::Exact);++ provider.try_create_token(path, &original).await.unwrap();+ assert_eq!(+ provider.read_token(path).await.unwrap(),+ Some(original.clone())+ );+ assert!(provider.refresh_token(path, "owner-a", 200).await.unwrap());+ assert_eq!(+ provider.read_token(path).await.unwrap(),+ Some(token("owner-a", 200, PathLockKind::Exact))+ );++ runtime+ .register_script(ScriptDefinition {+ id: TEST_PTTL_ID,+ redis_lua: TEST_PTTL_SCRIPT,+ })+ .unwrap();+ let ttl = runtime+ .execute_script(ScriptRequest {+ script_id: TEST_PTTL_ID.to_string(),+ keys: vec![provider.tokens_key_for_path(path).unwrap()],+ args: Vec::new(),+ })+ .await+ .unwrap()+ .decode()+ .unwrap();+ assert!(matches!(ttl, ScriptValue::Integer(value) if value > 0 && value <= 2_000));++ assert!(provider.remove_token(path, "owner-a", false).await.unwrap());+ assert_eq!(provider.read_token(path).await.unwrap(), None);+ runtime.close().await.unwrap();+ }++ /// Verify Lua rejects conflicting owners without partially writing a batch.+ #[tokio::test]+ async fn provider_atomic_batch_is_all_or_nothing() {+ let Some((runtime, provider)) = test_provider("atomic").await else {+ return;+ };+ let initial = vec![request("/local/account-a/locked", PathLockKind::Tree)];+ let acquired = provider+ .try_acquire_batch_atomic(&initial, "owner-a", 100, 0)+ .await+ .unwrap()+ .unwrap();+ assert!(matches!(+ acquired.as_slice(),+ [AtomicAcquisition {+ handle,+ change: AcquisitionChange::Created { .. },+ }] if handle == "/local/account-a/locked"+ ));++ let conflicting = vec![+ request("/local/account-a/free", PathLockKind::Exact),+ request("/local/account-a/locked/child", PathLockKind::Exact),+ ];+ assert!(matches!(+ provider+ .try_acquire_batch_atomic(&conflicting, "owner-b", 101, 0)+ .await,+ Err(PathLockError::Conflict { lock_path, .. })+ if lock_path == "/local/account-a/locked"+ ));+ assert_eq!(+ provider.read_token("/local/account-a/free").await.unwrap(),+ None+ );++ provider+ .try_acquire_batch_atomic(+ &[request("/local/account-a/a", PathLockKind::Exact)],+ "owner-a",+ 102,+ 0,+ )+ .await+ .unwrap();+ assert!(provider+ .try_acquire_batch_atomic(+ &[request("/local/account-a/a/b", PathLockKind::Exact)],+ "owner-b",+ 103,+ 0,+ )+ .await+ .is_ok());+ assert!(provider+ .try_acquire_batch_atomic(&[request("/", PathLockKind::Tree)], "owner-c", 104, 0,)+ .await+ .is_ok());++ let race = [request("/local/account-a/race", PathLockKind::Exact)];+ let (first, second) = tokio::join!(+ provider.try_acquire_batch_atomic(&race, "owner-a", 200, 0),+ provider.try_acquire_batch_atomic(&race, "owner-b", 200, 0),+ );+ assert_ne!(first.is_ok(), second.is_ok());+ assert!(+ matches!(first, Err(PathLockError::Conflict { .. }))+ || matches!(second, Err(PathLockError::Conflict { .. }))+ );+ runtime.close().await.unwrap();+ }++ /// Verify rollback removes creates and restores same-owner upgrades.+ #[tokio::test]+ async fn provider_atomic_rollback_restores_previous_state() {+ let Some((runtime, provider)) = test_provider("rollback").await else {+ return;+ };+ let exact = vec![request("/local/account-a/a", PathLockKind::Exact)];+ let created = provider+ .try_acquire_batch_atomic(&exact, "owner-a", 100, 0)+ .await+ .unwrap()+ .unwrap();+ provider+ .rollback_acquisitions_atomic(&created, "owner-a")+ .await+ .unwrap()+ .unwrap();+ assert_eq!(+ provider.read_token("/local/account-a/a").await.unwrap(),+ None+ );++ provider+ .try_acquire_batch_atomic(&exact, "owner-a", 200, 0)+ .await+ .unwrap();+ let tree = vec![request("/local/account-a/a", PathLockKind::Tree)];+ let upgraded = provider+ .try_acquire_batch_atomic(&tree, "owner-a", 300, 0)+ .await+ .unwrap()+ .unwrap();+ provider+ .rollback_acquisitions_atomic(&upgraded, "owner-a")+ .await+ .unwrap()+ .unwrap();+ assert_eq!(+ provider.read_token("/local/account-a/a").await.unwrap(),+ Some(token("owner-a", 200, PathLockKind::Exact))+ );++ let changed = provider+ .try_acquire_batch_atomic(+ &[request("/local/account-a/changed", PathLockKind::Exact)],+ "owner-a",+ 400,+ 0,+ )+ .await+ .unwrap()+ .unwrap();+ assert!(provider+ .refresh_token("/local/account-a/changed", "owner-a", 500)+ .await+ .unwrap());+ assert!(matches!(+ provider+ .rollback_acquisitions_atomic(&changed, "owner-a")+ .await,+ Err(PathLockError::Io(_))+ ));+ assert_eq!(+ provider+ .read_token("/local/account-a/changed")+ .await+ .unwrap(),+ Some(token("owner-a", 500, PathLockKind::Exact))+ );++ runtime.close().await.unwrap();+ }++ /// Verify Redis handoff can be adopted by another manager using logical handles.+ #[tokio::test]+ async fn manager_redis_adopts_handoff_across_managers() {+ let Some((runtime, first, second, key)) = test_managers("handoff").await else {+ return;+ };+ let lease = first+ .acquire_tree("/local/account-a/a", Duration::ZERO, None)+ .await+ .unwrap();+ let handoff = first.to_handoff(&lease);+ first.handoff(&lease).await.unwrap();++ let adopted = second.adopt(&handoff).await.unwrap();++ assert_eq!(adopted.lease.lock_paths, vec!["/local/account-a/a"]);+ second.release(&adopted).await.unwrap();+ let legacy = PathLockHandoffRef {+ lease_ref: None,+ owner_id: "owner-a".to_string(),+ lock_paths: vec!["/local/account-a/a".to_string()],+ covered_paths: Vec::new(),+ };+ assert!(matches!(+ second.adopt(&legacy).await,+ Err(PathLockError::HandoffFailed(_))+ ));+ runtime.del(&[key]).await.unwrap();+ runtime.close().await.unwrap();+ }++ /// Verify reentrant upgrades, downgrades, refresh, and partial release use logical handles.+ #[tokio::test]+ async fn manager_redis_preserves_lease_lifecycle_semantics() {+ let Some((runtime, first, second, key)) = test_managers("lifecycle").await else {+ return;+ };+ let exact = first+ .acquire_exact("/local/account-a/a/", Duration::ZERO, None)+ .await+ .unwrap();+ assert_eq!(exact.lease.lock_paths, vec!["/local/account-a/a"]);+ assert!(first.is_locked("/local/account-a/a/", true).await.unwrap());+ let tree = first+ .acquire_tree(+ "/local/account-a/a",+ Duration::ZERO,+ Some((&exact.lease.lease_ref, &exact.ownership_ref)),+ )+ .await+ .unwrap();+ assert_eq!(first.refresh(&exact).await.unwrap(), "refreshed");+ first.release(&tree).await.unwrap();++ let child = second+ .acquire_exact("/local/account-a/a/child", Duration::ZERO, None)+ .await+ .unwrap();+ second.release(&child).await.unwrap();+ first.release(&exact).await.unwrap();+ assert!(!first.is_locked("/local/account-a/a", true).await.unwrap());++ let batch = first+ .acquire_exact_batch(+ &[+ "/local/account-a/x".to_string(),+ "/local/account-a/y".to_string(),+ ],+ Duration::ZERO,+ None,+ )+ .await+ .unwrap();+ first+ .release_selected(&batch, &["/local/account-a/x".to_string()])+ .await+ .unwrap();+ let released = second+ .acquire_exact("/local/account-a/x", Duration::ZERO, None)+ .await+ .unwrap();+ assert!(second+ .acquire_exact("/local/account-a/y", Duration::from_millis(1), None,)+ .await+ .is_err());+ second.release(&released).await.unwrap();+ first.release(&batch).await.unwrap();++ runtime.del(&[key]).await.unwrap();+ runtime.close().await.unwrap();+ }++ /// Verify stale foreign tokens are replaced while same-owner reentry preserves time.+ #[tokio::test]+ async fn provider_stale_cleanup_preserves_same_owner_reentry() {+ let Some((runtime, provider)) = test_provider("stale").await else {+ return;+ };+ let same_path = "/local/account-a/same";+ provider+ .try_create_token(same_path, &token("owner-a", 1, PathLockKind::Exact))+ .await+ .unwrap();+ let reentrant = provider+ .try_acquire_batch_atomic(+ &[request(same_path, PathLockKind::Exact)],+ "owner-a",+ 100,+ 50,+ )+ .await+ .unwrap()+ .unwrap();+ assert!(matches!(reentrant[0].change, AcquisitionChange::Reentrant));+ assert_eq!(+ provider.read_token(same_path).await.unwrap(),+ Some(token("owner-a", 1, PathLockKind::Exact))+ );+ assert_eq!(+ provider+ .is_path_locked_atomic(same_path, 100, 50, true)+ .await+ .unwrap(),+ Some(false)+ );+ assert_eq!(+ provider+ .is_path_locked_atomic(same_path, 100, 50, false)+ .await+ .unwrap(),+ Some(true)+ );++ let foreign_path = "/local/account-a/foreign";+ provider+ .try_create_token(foreign_path, &token("owner-b", 1, PathLockKind::Exact))+ .await+ .unwrap();+ provider+ .try_acquire_batch_atomic(+ &[request(foreign_path, PathLockKind::Exact)],+ "owner-a",+ 100,+ 50,+ )+ .await+ .unwrap();+ assert_eq!(+ provider+ .read_token(foreign_path)+ .await+ .unwrap()+ .unwrap()+ .owner_id,+ "owner-a"+ );++ runtime.close().await.unwrap();+ }++ /// Verify an out-of-range token is rejected before an atomic upgrade writes.+ #[tokio::test]+ async fn provider_invalid_u128_token_does_not_modify_hash() {+ let Some((runtime, provider)) = test_provider("invalid-u128").await else {+ return;+ };+ runtime+ .register_script(ScriptDefinition {+ id: TEST_HASH_ID,+ redis_lua: TEST_HASH_SCRIPT,+ })+ .unwrap();+ let path = "/local/account-a/invalid";+ let key = provider.tokens_key_for_path(path).unwrap();+ let invalid = "owner-a:340282366920938463463374607431768211456:E";+ runtime+ .execute_script(ScriptRequest {+ script_id: TEST_HASH_ID.to_string(),+ keys: vec![key.clone()],+ args: vec![+ RedisPathLockProvider::bytes("set"),+ RedisPathLockProvider::bytes(path),+ RedisPathLockProvider::bytes(invalid),+ ],+ })+ .await+ .unwrap();++ assert!(matches!(+ provider+ .try_acquire_batch_atomic(&[request(path, PathLockKind::Tree)], "owner-a", 100, 0,)+ .await,+ Err(PathLockError::InvalidToken(_))+ ));+ let raw = runtime+ .execute_script(ScriptRequest {+ script_id: TEST_HASH_ID.to_string(),+ keys: vec![key],+ args: vec![+ RedisPathLockProvider::bytes("get"),+ RedisPathLockProvider::bytes(path),+ ],+ })+ .await+ .unwrap()+ .decode()+ .unwrap();+ assert_eq!(raw, ScriptValue::Bytes(invalid.as_bytes().to_vec()));++ runtime.close().await.unwrap();+ }++ /// Verify an unknown atomic write result never publishes a local lease.+ #[tokio::test]+ async fn manager_unknown_atomic_result_does_not_publish_lease() {+ let provider = Arc::new(FaultProvider::new(AtomicFault::WriteThenIo));+ let manager = PathLockManager::new(+ Arc::new(MemFileSystem::new()),+ provider.clone(),+ PathLockConfig {+ provider: "cache".to_string(),+ namespace: Some("timeout-test".to_string()),+ ..PathLockConfig::default()+ },+ );++ assert!(matches!(+ manager+ .acquire_exact("/timeout", Duration::ZERO, None)+ .await,+ Err(PathLockError::Io(_))+ ));+ assert_eq!(manager.observe().await.active_locks, 0);+ assert!(provider.read_token("/timeout").await.unwrap().is_some());+ }++ /// Verify Manager never performs non-atomic stale cleanup after a logical conflict.+ #[tokio::test]+ async fn manager_logical_conflict_does_not_remove_stale_snapshot() {+ let provider = Arc::new(FaultProvider::new(AtomicFault::Conflict));+ let manager = PathLockManager::new(+ Arc::new(MemFileSystem::new()),+ provider.clone(),+ PathLockConfig {+ provider: "cache".to_string(),+ namespace: Some("race-test".to_string()),+ lock_expire_secs: 1.0,+ ..PathLockConfig::default()+ },+ );++ assert!(manager+ .acquire_exact("/race", Duration::from_millis(5), None)+ .await+ .is_err());+ assert_eq!(provider.remove_calls.load(Ordering::SeqCst), 0);+ }++ /// Verify optional cluster and sentinel topology contracts.+ #[tokio::test]+ async fn topology_cluster_and_sentinel() {+ if let Some(endpoints) = topology_endpoints("REDIS_CLUSTER_TEST_URLS") {+ exercise_topology("cluster", endpoints, None, "cluster").await;+ }+ if let (Some(endpoints), Ok(master)) = (+ topology_endpoints("REDIS_SENTINEL_TEST_URLS"),+ std::env::var("REDIS_SENTINEL_TEST_MASTER"),+ ) {+ exercise_topology("sentinel", endpoints, Some(master), "sentinel").await;+ }+ }++ /// Measure HASH-only atomic batch latency for representative lock counts.+ #[tokio::test]+ #[ignore = "manual Redis performance baseline"]+ async fn perf_hash_only_batches() {+ let Some((runtime, provider)) = test_provider("perf").await else {+ return;+ };+ for count in [100usize, 500, 1_000] {+ let requests = (0..count)+ .map(|index| PathLockRequest {+ path: format!("/local/account-a/perf/{index}"),+ kind: PathLockKind::Exact,+ })+ .collect::<Vec<_>>();+ let start = Instant::now();+ let acquired = provider+ .try_acquire_batch_atomic(&requests, "perf-owner", 100, 0)+ .await+ .unwrap()+ .unwrap();+ let elapsed = start.elapsed();+ println!(+ "pathlock HASH-only count={count} acquire_ms={}",+ elapsed.as_secs_f64() * 1_000.0+ );+ provider+ .rollback_acquisitions_atomic(&acquired, "perf-owner")+ .await+ .unwrap();+ }++ runtime.close().await.unwrap();+ }+}diff --git a/crates/ragfs/src/lock/manager.rs b/crates/ragfs/src/lock/manager.rsindex 2bcc45d62..dab28f1d2 100644--- a/crates/ragfs/src/lock/manager.rs+++ b/crates/ragfs/src/lock/manager.rs@@ -17,7 +17,7 @@ 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::provider::{AcquisitionChange, AtomicAcquisition, PathLockHandleMode, PathLockProvider};use super::resolver::{LockPathResolver, ResolvedExactPaths};use super::types::{BorrowedPathLockLease, LockToken, OwnedPathLockLease, PathLockConflict, PathLockError,@@ -28,8 +28,10 @@ use super::types::{/// Configuration for the PathLockManager.#[derive(Debug, Clone)]pub struct PathLockConfig {- /// Built-in provider name: `filesystem` or `memory`.+ /// Built-in provider name: `filesystem`, `memory`, or `cache`.pub provider: String,+ /// OpenViking instance name used by the cache-backed provider.+ pub namespace: Option<String>,/// Default wait timeout for auto-acquired locks.pub lock_timeout_secs: f64,/// Seconds after which a lock token is considered stale.@@ -40,6 +42,7 @@ impl Default for PathLockConfig {fn default() -> Self {Self {provider: "filesystem".to_string(),+ namespace: None,lock_timeout_secs: 0.0,lock_expire_secs: 30.0,}@@ -112,16 +115,6 @@ struct LeaseEntry {last_active_at: Instant,}-#[derive(Debug)]-enum AcquisitionChange {- Created,- Reentrant,- Upgraded {- previous: LockToken,- replacement: LockToken,- },-}-#[derive(Debug)]enum DowngradeTokenResult {Downgraded,@@ -642,12 +635,7 @@ impl PathLockManager {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()- };+ let path = Self::normalize_path(&request.path);by_path.entry(path).and_modify(|kind| {@@ -671,10 +659,24 @@ impl PathLockManager {normalized}+ /// Normalize one logical path using the existing PathLock trailing-slash rule.+ fn normalize_path(path: &str) -> String {+ let trimmed = path.trim_end_matches('/');+ if trimmed.is_empty() {+ "/".to_string()+ } else {+ trimmed.to_string()+ }+ }++ /// Return the configured lock expiry in nanoseconds.+ fn lock_expire_ns(&self) -> u128 {+ (self.config.lock_expire_secs * 1_000_000_000.0) as u128+ }+/// 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+ now_ns.saturating_sub(token.time_ns) > self.lock_expire_ns()}/// Return whether an acquire-loop error should be retried within the wait budget.@@ -900,7 +902,7 @@ impl PathLockManager {});}- if pre_conflict {+ if pre_conflict && self.provider.handle_mode() == PathLockHandleMode::LockPath {if let PathLockError::Conflict { ref lock_path, .. } = &err {let token = match self.provider.read_token(lock_path).await {Ok(token) => token,@@ -943,7 +945,7 @@ impl PathLockManager {owner_id: owner_id.clone(),lock_paths: acquired_lock_paths.iter()- .map(|(lock_path, _)| lock_path.clone())+ .map(|acquisition| acquisition.handle.clone()).collect(),covered_paths: sorted.clone(),};@@ -998,7 +1000,23 @@ impl PathLockManager {&self,requests: &[PathLockRequest],owner_id: &str,- ) -> Result<Vec<(String, AcquisitionChange)>, (PathLockError, bool)> {+ ) -> Result<Vec<AtomicAcquisition>, (PathLockError, bool)> {+ let now_ns = Self::now_ns();+ match self+ .provider+ .try_acquire_batch_atomic(+ requests,+ owner_id,+ now_ns,+ now_ns.saturating_sub(self.lock_expire_ns()),+ )+ .await+ {+ Ok(Some(acquisitions)) => return Ok(acquisitions),+ Ok(None) => {}+ Err(error) => return Err((error, true)),+ }+let mut acquired = Vec::new();let mut exact_resolutions: HashMap<String, ResolvedExactPaths> = HashMap::new();let acquisition: PathLockResult<()> = async {@@ -1018,7 +1036,10 @@ impl PathLockManager {let change = self.try_acquire_one(&lock_path, owner_id, PathLockKind::Exact).await?;- acquired.push((lock_path, change));+ acquired.push(AtomicAcquisition {+ handle: lock_path,+ change,+ });}PathLockKind::Tree => {let lock_path = self.resolver.resolve_tree_lock_path(&request.path).await?;@@ -1036,7 +1057,10 @@ impl PathLockManager {let change = self.try_acquire_one(&lock_path, owner_id, PathLockKind::Tree).await?;- acquired.push((lock_path, change));+ acquired.push(AtomicAcquisition {+ handle: lock_path,+ change,+ });}}}@@ -1092,14 +1116,22 @@ impl PathLockManager {/// Roll back token changes made by one incomplete batch acquisition.async fn rollback_acquisitions(&self,- acquired_lock_paths: &[(String, AcquisitionChange)],+ acquired_lock_paths: &[AtomicAcquisition],owner_id: &str,) -> PathLockResult<()> {+ if let Some(result) = self+ .provider+ .rollback_acquisitions_atomic(acquired_lock_paths, owner_id)+ .await?+ {+ return Ok(result);+ }+let mut first_error = None;- for (lock_path, change) in acquired_lock_paths.iter().rev() {- let result = match change {- AcquisitionChange::Created => {- Self::remove_owned_token_with(&self.provider, lock_path, owner_id)+ for acquisition in acquired_lock_paths.iter().rev() {+ let result = match &acquisition.change {+ AcquisitionChange::Created { .. } => {+ Self::remove_owned_token_with(&self.provider, &acquisition.handle, owner_id).await.map(|_| ())}@@ -1109,12 +1141,13 @@ impl PathLockManager {replacement,} => match self.provider- .compare_and_write_token(lock_path, replacement, previous)+ .compare_and_write_token(&acquisition.handle, replacement, previous).await{Ok(true) => Ok(()),Ok(false) => Err(PathLockError::Io(format!(- "failed to roll back token upgrade at '{lock_path}'"+ "failed to roll back token upgrade at '{}'",+ acquisition.handle))),Err(error) => Err(error),},@@ -1184,7 +1217,7 @@ impl PathLockManager {self.provider.try_create_token(lock_path, &token).await?;debug!(lock_path = %lock_path, owner_id = %owner_id, kind = ?kind, "created new pathlock token");- Ok(AcquisitionChange::Created)+ Ok(AcquisitionChange::Created { replacement: token })}/// Check concrete lock-file paths for a live token owned by another owner.@@ -1747,6 +1780,12 @@ impl PathLockManager {}let legacy_handoff = handoff.covered_paths.is_empty();+ let handle_mode = self.provider.handle_mode();+ if handle_mode == PathLockHandleMode::LogicalPath && legacy_handoff {+ return Err(PathLockError::HandoffFailed(+ "logical-path provider handoff requires covered_paths".to_string(),+ ));+ }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(),@@ -1759,38 +1798,52 @@ impl PathLockManager {// 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"- )));+ let expected_kind = match handle_mode {+ PathLockHandleMode::LogicalPath => {+ let request = &handoff.covered_paths[index];+ let expected_path = Self::normalize_path(&request.path);+ if lp != &expected_path {+ return Err(PathLockError::InvalidRequest(format!(+ "handoff coverage '{}' does not match logical lock path '{lp}'",+ request.path+ )));+ }+ request.kind}- } else {- let request = &handoff.covered_paths[index];- let expected_paths = match request.kind {- PathLockKind::Exact => {- self.resolver- .resolve_exact_conflict_paths(&request.path)- .await?+ PathLockHandleMode::LockPath 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"+ )));}- PathLockKind::Tree => {- vec![self.resolver.resolve_tree_lock_path(&request.path).await?]+ }+ PathLockHandleMode::LockPath => {+ 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+ )));}- };- if !expected_paths.contains(lp) {- return Err(PathLockError::InvalidRequest(format!(- "handoff coverage '{}' does not map to lock path '{lp}'",- request.path- )));+ request.kind}- request.kind};expected_kinds.push(expected_kind);}@@ -1882,6 +1935,19 @@ impl PathLockManager {/// 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();+ let normalized_path = Self::normalize_path(path);+ if let Some(locked) = self+ .provider+ .is_path_locked_atomic(+ &normalized_path,+ now_ns,+ now_ns.saturating_sub(self.lock_expire_ns()),+ ignore_stale,+ )+ .await?+ {+ return Ok(locked);+ }// Check own .path.ovlock.let dir_lock = format!("{}/{}", path.trim_end_matches('/'), PATH_LOCK_FILE);diff --git a/crates/ragfs/src/lock/mod.rs b/crates/ragfs/src/lock/mod.rsindex e50e3c9cc..67d1a60e2 100644--- a/crates/ragfs/src/lock/mod.rs+++ b/crates/ragfs/src/lock/mod.rs@@ -1,18 +1,20 @@//! 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.+//! This module provides exact-path and tree-path locks backed by lock files,+//! process memory, or Redis.//!//! # Architecture//!//! - [`PathLockManager`] is the single source of truth for lock semantics.-//! - [`PathLockProvider`] is the storage abstraction (memory or filesystem).+//! - [`PathLockProvider`] is the storage abstraction.//! - [`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;+#[cfg(feature = "cache")]+mod cache_provder;pub mod manager;pub mod metrics;pub mod provider;@@ -21,9 +23,14 @@ pub mod types;pub mod wrapper;pub use codec::LockTokenCodec;+#[cfg(feature = "cache")]+pub use cache_provder::RedisPathLockProvider;pub use manager::{AutoPathLockAction, PathLockConfig, PathLockManager};pub use metrics::LockMetrics;-pub use provider::{FilesystemPathLockProvider, MemoryPathLockProvider, PathLockProvider};+pub use provider::{+ AcquisitionChange, AtomicAcquisition, FilesystemPathLockProvider, MemoryPathLockProvider,+ PathLockHandleMode, PathLockProvider,+};pub use resolver::LockPathResolver;pub use types::{BorrowedPathLockLease, LockToken, OwnedPathLockLease, PathLockConflict, PathLockHandoffRef,diff --git a/crates/ragfs/src/lock/provider.rs b/crates/ragfs/src/lock/provider.rsindex 4219e83d3..d6ec86b89 100644--- a/crates/ragfs/src/lock/provider.rs+++ b/crates/ragfs/src/lock/provider.rs@@ -1,7 +1,7 @@//! 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`.+//! The provider owns token storage. Backends with transactional storage may also+//! implement the optional atomic capabilities used by `PathLockManager`.use std::collections::HashMap;use std::sync::Arc;@@ -14,7 +14,44 @@ use crate::core::FileSystem;use crate::crypto;use super::codec::LockTokenCodec;-use super::types::{LockToken, PathLockError, PathLockResult};+use super::types::{LockToken, PathLockError, PathLockRequest, PathLockResult};++/// Representation used for handles stored in a PathLock lease.+#[derive(Debug, Clone, Copy, PartialEq, Eq)]+pub enum PathLockHandleMode {+ /// Handles are resolver-generated lock-file paths.+ LockPath,+ /// Handles are normalized logical paths.+ LogicalPath,+}++/// Token mutation made during one lock acquisition.+#[derive(Debug, Clone, PartialEq, Eq)]+pub enum AcquisitionChange {+ /// A new token was created.+ Created {+ /// Token written by the provider.+ replacement: LockToken,+ },+ /// The same owner already held an equal or stronger token.+ Reentrant,+ /// A same-owner Exact token became Tree.+ Upgraded {+ /// Token restored if local lease publication fails.+ previous: LockToken,+ /// Tree token written by the provider.+ replacement: LockToken,+ },+}++/// One mutation made by an atomic provider acquisition.+#[derive(Debug, Clone, PartialEq, Eq)]+pub struct AtomicAcquisition {+ /// Provider handle stored in the PathLock lease.+ pub handle: String,+ /// Token mutation used by rollback.+ pub change: AcquisitionChange,+}/// Storage abstraction for lock tokens. Only `PathLockManager` should call these methods.#[async_trait]@@ -22,6 +59,42 @@ pub trait PathLockProvider: Send + Sync {/// Human-readable provider name for config/logging/metrics.fn name(&self) -> &'static str;+ /// Return how this provider represents lease handles.+ fn handle_mode(&self) -> PathLockHandleMode {+ PathLockHandleMode::LockPath+ }++ /// Attempt one atomic batch acquisition when supported.+ async fn try_acquire_batch_atomic(+ &self,+ _requests: &[PathLockRequest],+ _owner_id: &str,+ _now_ns: u128,+ _stale_before_ns: u128,+ ) -> PathLockResult<Option<Vec<AtomicAcquisition>>> {+ Ok(None)+ }++ /// Roll back one completed atomic acquisition when supported.+ async fn rollback_acquisitions_atomic(+ &self,+ _acquisitions: &[AtomicAcquisition],+ _owner_id: &str,+ ) -> PathLockResult<Option<()>> {+ Ok(None)+ }++ /// Return whether one path is covered by a live token when supported.+ async fn is_path_locked_atomic(+ &self,+ _path: &str,+ _now_ns: u128,+ _stale_before_ns: u128,+ _ignore_stale: bool,+ ) -> PathLockResult<Option<bool>> {+ Ok(None)+ }+/// Read the token at `lock_path`, returning `None` if no token exists.async fn read_token(&self, lock_path: &str) -> PathLockResult<Option<LockToken>>;diff --git a/docs/en/concepts/09-transaction.md b/docs/en/concepts/09-transaction.mdindex 450114160..ff8a8110f 100644--- a/docs/en/concepts/09-transaction.md+++ b/docs/en/concepts/09-transaction.md@@ -41,7 +41,7 @@ Storage Layer (VikingFS, VectorDB, QueueManager)### Component 1: PathLockEngine + LockManager + LockContext (Path Lock System)-**PathLockEngine** implements file-based distributed locks with two lock types — EXACT and TREE — using fencing tokens to prevent TOCTOU races and automatic stale lock detection and cleanup.+**PathLockEngine** implements provider-backed distributed locks with two lock types — EXACT and TREE — using ownership tokens to prevent TOCTOU races and automatic stale lock detection and cleanup. The default provider stores lock files in AGFS; the cache provider stores tokens in Redis.**LockHandle** is a lightweight lock holder token:@@ -49,7 +49,7 @@ Storage Layer (VikingFS, VectorDB, QueueManager)@dataclassclass LockHandle:id: str # Unique ID used to generate fencing tokens- locks: list[str] # Acquired lock file paths+ locks: list[str] # Provider handles: lock file paths or logical pathscreated_at: float # Handle creation timelast_active_at: float # Last successful acquire/refresh time```@@ -274,11 +274,11 @@ The lock mechanism uses two lock types to handle different conflict patterns:| **TREE** | Conflict | Conflict | Conflict | Conflict |- **EXACT (E)**: Locks one concrete path. It can protect files, directory names, and not-yet-created target paths. Blocks if any ancestor holds a TreeLock.-- **TREE (T)**: Used for directory delete, directory move, resource lifecycle protection, and similar subtree-level operations. Logically covers the entire subtree but only writes **one lock file** at the root. Before acquiring, scans all descendants and ancestor directories for conflicting locks. If the target directory is missing, conflicts are checked first; only then is the directory created and locked. If a later double-check finds a new conflict, the acquire fails or retries without rolling back the empty directory.+- **TREE (T)**: Used for directory delete, directory move, resource lifecycle protection, and similar subtree-level operations. Logically covers the entire subtree but stores one provider token for the root path. Conflict checks cover descendants and Tree-locked ancestors within the provider's scope. The filesystem provider may create a missing target directory to place its lock file.## Lock Mechanism-### Lock Protocol+### Filesystem Provider Lock ProtocolLock file paths:@@ -295,7 +295,30 @@ Lock file content (Fencing Token):Where `lock_type` is `E` (EXACT) or `T` (TREE).-### Lock Acquisition (EXACT mode)+### Cache Provider Lock Protocol++The cache provider stores the same token format in Redis HASH fields. It uses+Lua scripts to atomically check conflicts and write a complete batch:++```text+field = logical_path+value = owner_id:time_ns:lock_type+```++HASH keys are isolated by path scope:++```text+ov:pathlock:{namespace}:global:tokens+ov:pathlock:{namespace}:scope:_system:tokens+ov:pathlock:{namespace}:scope:account:{account}:tokens+```++All keys use `{namespace}` as the Redis Cluster hash tag. Exact acquisition+reads the target and ancestors with `HMGET`; Tree acquisition scans only its+scope HASH with `HGETALL`. Global `/` and `/local` locks do not scan account+or `_system` HASHes. Cross-scope batches are rejected.++### Filesystem Lock Acquisition (EXACT mode)```loop until timeout (poll interval: 200ms):@@ -317,7 +340,7 @@ loop until timeout (poll interval: 200ms):Timeout (default 0 = no-wait) raises LockAcquisitionError```-### Lock Acquisition (TREE mode)+### Filesystem Lock Acquisition (TREE mode)```loop until timeout (poll interval: 200ms):@@ -357,11 +380,11 @@ for conflicts first:### Lock Expiry Cleanup-**Stale lock detection**: PathLockEngine checks the fencing token timestamp. Locks older than `lock_expire` (default 30s) are considered stale and are removed automatically during acquisition.+**Stale lock detection**: PathLockEngine checks the ownership token timestamp. Locks older than `lock_expire` (default 30s) are considered stale and are removed automatically during acquisition.-**In-process cleanup**: LockManager checks active LockHandles every 60 seconds. Handles that still own lock files but have been inactive for longer than `lock_expire` are force-released.+**In-process cleanup**: LockManager checks active LockHandles every 60 seconds. Handles that still own provider tokens but have been inactive for longer than `lock_expire` are force-released.-**Orphan locks**: Lock files left behind after a process crash are automatically removed via stale lock detection when any operation next attempts to acquire a lock on the same path.+**Orphan locks**: Provider tokens left behind after a process crash are automatically removed via stale lock detection when a later acquisition checks the same path or scope.## Crash Recovery@@ -370,7 +393,7 @@ After startup, QueueManager resumes persisted `session_commit` jobs:| Scenario | Recovery action ||----------|----------------|| session_memory extraction crash | Recover Phase 2 from archive and continue the `session_commit` job |-| Crash while holding lock | Lock file remains in AGFS; stale detection auto-cleans on next acquisition (default 30s expiry) |+| Crash while holding lock | Provider token remains; stale detection auto-cleans on a later matching acquisition (default 30s expiry) || Crash after enqueue, before worker processes | QueueFS SQLite persistence; worker auto-pulls after restart || Orphan index | Cleaned on L2 on-demand load |@@ -386,7 +409,14 @@ After startup, QueueManager resumes persisted `session_commit` jobs:## Configuration-Path locks are enabled by default with no extra configuration needed. Prefer `storage.agfs.pathlock` for expiry settings. The runtime wait timeout is fixed at `0.0` seconds and no longer accepts external configuration. `storage.transaction` remains only as a legacy compatibility layer: `lock_timeout` is deprecated and ignored, `lock_expire` is automatically mapped when the new field is unset, and `redo_recovery_enabled` is deprecated and ignored.+Path locks are enabled by default with the `filesystem` provider. Use+`storage.agfs.pathlock.provider=cache` for Redis-backed coordination between+processes. Cache-backed PathLock requires a top-level Redis Cache Provider and+a non-empty PathLock namespace. The runtime wait timeout is fixed at `0.0`+seconds. `storage.transaction` remains only as a legacy compatibility layer:+`lock_timeout` is deprecated and ignored, `lock_expire` is automatically+mapped when the new field is unset, and `redo_recovery_enabled` is deprecated+and ignored.Recommended configuration:@@ -395,6 +425,7 @@ Recommended configuration:"storage": {"agfs": {"pathlock": {+ "provider": "filesystem","lock_expire_secs": 30.0}}@@ -402,6 +433,35 @@ Recommended configuration:}```+Redis-backed configuration:++```json+{+ "cache": {+ "provider": "redis",+ "params": {+ "mode": "standalone",+ "endpoints": ["redis://127.0.0.1:6379"]+ }+ },+ "storage": {+ "agfs": {+ "pathlock": {+ "provider": "cache",+ "namespace": "production",+ "lock_expire_secs": 30.0+ }+ }+ }+}+```++| Parameter | Type | Description | Default |+|-----------|------|-------------|---------|+| `provider` | str | `filesystem`, `memory`, or `cache` | `filesystem` |+| `namespace` | str or null | Required when `provider=cache`; identifies one OpenViking deployment | `null` |+| `lock_expire_secs` | float | Seconds before an unrefreshed lock becomes stale | `30.0` |+Legacy compatibility form:```jsondiff --git a/docs/en/guides/01-configuration.md b/docs/en/guides/01-configuration.mdindex 04231deea..1df466704 100644--- a/docs/en/guides/01-configuration.md+++ b/docs/en/guides/01-configuration.md@@ -1130,7 +1130,7 @@ Notes:See the [Multi-Write Storage Guide](./13-multi-write-storage.md) for more examples.-##### Global Cache Provider and CacheFS Configuration+##### Global Cache Provider, CacheFS, and PathLock ConfigurationThe top-level `cache` section is a sibling of `storage`. Its public shape is Provider-neutral:@@ -1149,6 +1149,15 @@ The top-level `cache` section is a sibling of `storage`. Its public shape is Pro| `traversal_mode` | str | `backend` or `cached_traversal` | `backend` || `bypass_prefixes` | array[str] | Path prefixes that bypass cache | `[]` |+`storage.agfs.pathlock` selects the PathLock storage provider:++| Parameter | Type | Description | Default |+|-----------|------|-------------|---------|+| `provider` | str | `filesystem`, `memory`, or `cache`; `cache` uses the shared Redis CacheRuntime | `filesystem` |+| `namespace` | str (optional) | OpenViking instance name used in Redis PathLock keys; required when `provider=cache` | `null` |+| `lock_expire_secs` | float | Seconds before an unrefreshed lock becomes stale; must be at least `1.0` | `30.0` |+| `lock_timeout_secs` | float | Deprecated and ignored; runtime wait timeout remains `0.0` | `0.0` |+```json{"cache": {@@ -1174,13 +1183,18 @@ The top-level `cache` section is a sibling of `storage`. Its public shape is Pro"queuefs": {"backend": "cache","cache_key_prefix": "production"+ },+ "pathlock": {+ "provider": "cache",+ "namespace": "production",+ "lock_expire_secs": 30.0}}}}```-The canonical configuration has no global `cache.enabled`. CacheRuntime is initialized when CacheFS or QueueFS selects `backend=cache`. When all modules use local backends, `cache.params` is not parsed and no Provider connection is opened.+The canonical configuration has no global `cache.enabled`. CacheRuntime is initialized when CacheFS or QueueFS selects `backend=cache`, or when PathLock selects `provider=cache`. Cache-backed PathLock currently requires `cache.provider=redis`; DynamicProvider is not supported for PathLock. When all modules use local providers, `cache.params` is not parsed and no Provider connection is opened.This is a breaking configuration change. `storage.agfs.cache`, `storage.agfs.queuefs.backend="redis"`, and `storage.agfs.queuefs.redis` are rejected. Move Provider settings to top-level `cache.provider/cache.params`, select `cachefs.backend="cache"` or `queuefs.backend="cache"`, use Redis `mode="standalone"` instead of `singleton`, and use `rediss://` instead of `tls_enabled`.@@ -1745,7 +1759,7 @@ For startup and deployment details see [Deployment](./03-deployment.md), for aut## storage.transaction Section-`storage.transaction` is deprecated and kept only for legacy compatibility. Use `storage.agfs.pathlock` only for active PathLock expiry configuration. When legacy fields are still present, OpenViking logs a warning at runtime; `lock_timeout` is deprecated and ignored, `lock_expire` is automatically mapped when the new field is unset, and `redo_recovery_enabled` is ignored.+`storage.transaction` is deprecated and kept only for legacy compatibility. Use `storage.agfs.pathlock` for the active PathLock provider, namespace, and expiry configuration. When legacy fields are still present, OpenViking logs a warning at runtime; `lock_timeout` is deprecated and ignored, `lock_expire` is automatically mapped when the new field is unset, and `redo_recovery_enabled` is ignored.Recommended configuration:@@ -1754,6 +1768,7 @@ Recommended configuration:"storage": {"agfs": {"pathlock": {+ "provider": "filesystem","lock_expire_secs": 30.0}}diff --git a/docs/en/guides/14-ragfs-cache.md b/docs/en/guides/14-ragfs-cache.mdindex 60089669a..d4352b919 100644--- a/docs/en/guides/14-ragfs-cache.md+++ b/docs/en/guides/14-ragfs-cache.md@@ -2,13 +2,16 @@RAGFS cache is an optional read-cache layer for OpenViking. It speeds up full file reads and directory reads. It is only an acceleration layer, not the source of truth; backend filesystem data remains authoritative.-Assumptions:+CachedFileSystem assumptions:- Only one OpenViking / RAGFS process writes to the same namespace.- File and directory changes go through RAGFS.- The backend is not modified externally by bypassing RAGFS.- After a cache Provider successfully writes or deletes one key, later reads of that key do not return the old value.+These assumptions apply to the read-cache layer. QueueFS and PathLock also use+CacheRuntime, but define their own consistency rules.+## Quick StartFor first-time setup, complete the base configuration first:@@ -42,6 +45,11 @@ Configure the global top-level `cache` Provider, then select `backend=cache` und"namespace": "openviking","max_file_size_bytes": 1048576,"bypass_prefixes": ["/queue", "/tmp"]+ },+ "pathlock": {+ "provider": "cache",+ "namespace": "openviking",+ "lock_expire_secs": 30.0}}}@@ -70,6 +78,33 @@ Available Providers:`MemoryMockProvider` is only used by unit and smoke tests; it is not a production configuration option.+### Cache-backed PathLock++Set `storage.agfs.pathlock.provider` to `cache` to coordinate path locks+between OpenViking processes through the shared Redis CacheRuntime.+`pathlock.namespace` is required and must be the same for every process in+one OpenViking deployment. Cache-backed PathLock only supports the built-in+Redis Provider.++Redis HASH keys are partitioned by logical path scope:++```text+ov:pathlock:{namespace}:global:tokens+ov:pathlock:{namespace}:scope:_system:tokens+ov:pathlock:{namespace}:scope:account:{account}:tokens+```++`{namespace}` is the Redis Cluster hash tag, so all PathLock keys for one+deployment remain in one slot. Tree conflict checks scan only the HASH for+the request scope. `/` and `/local` use the global HASH but do not scan+account or `_system` HASHes. A batch containing paths from different scopes+is rejected.++Do not run versions that use the legacy single HASH key together with versions+that use scoped keys. Stop old writers, wait at least+`2 * lock_expire_secs` for legacy keys to expire, and then start the new+version.+## Breaking Configuration ChangeLegacy cache configuration is no longer accepted. Migrate before upgrading:@@ -120,6 +155,14 @@ The top-level `cache` section is a sibling of `storage`:| `traversal_mode` | str | `"backend"` | Use backend traversal or `cached_traversal` for recursive APIs || `bypass_prefixes` | list[str] | `[]` | Path prefixes that always bypass cache |+`storage.agfs.pathlock` controls PathLock storage:++| Option | Type | Default | Description |+|--------|------|---------|-------------|+| `provider` | str | `"filesystem"` | `filesystem`, `memory`, or `cache` |+| `namespace` | str or null | `null` | Required OpenViking instance name when `provider=cache` |+| `lock_expire_secs` | float | `30.0` | Lock stale timeout; must be at least `1.0` |+Redis configuration:| Option | Default | Description |@@ -155,23 +198,28 @@ OpenViking uses `cache.params.library` to load the dynamic library. All remainin## Architecture-RAGFS splits caching into two layers:+RAGFS separates Provider access from its consumers:- `CachedFileSystem`: implements filesystem semantics, including cache hit/miss handling, backend fallback, cache fill, invalidation, generation checks, and metrics.- `CacheRuntime`: exposes common primitive operations and binds either the built-in RedisProvider or an external DynamicProvider during startup.+- `QueueFS` and `RedisPathLockProvider`: reuse the shared CacheRuntime for queue and distributed-lock storage. RedisPathLockProvider requires the built-in RedisProvider.Call flow:```textOpenViking-> RAGFS / MountableFS- -> CachedFileSystem- |-> CacheRuntime -> RedisProvider- | `-> DynamicProvider -> external shared library+ |-> CachedFileSystem ------\+ |-> QueueFS cache backend --+-> shared CacheRuntime -> RedisProvider+ `-> RedisPathLockProvider --/ `-> DynamicProvider`-> Backend FileSystem```-With this boundary, file, directory, rename, recursive delete, and write-after-invalidation logic live only in the common layer. An external Provider does not need to understand path semantics; it only supplies primitive key-value operations through the stable C ABI.+CachedFileSystem and QueueFS can use RedisProvider or DynamicProvider.+RedisPathLockProvider depends on Redis Lua execution and therefore only uses+RedisProvider. Filesystem semantics remain in CachedFileSystem; an external+Provider only supplies primitive key-value operations through the stable C+ABI.## Cache Objectsdiff --git a/docs/zh/concepts/09-transaction.md b/docs/zh/concepts/09-transaction.mdindex 15e4d5b12..947669f22 100644--- a/docs/zh/concepts/09-transaction.md+++ b/docs/zh/concepts/09-transaction.md@@ -40,7 +40,7 @@ Storage Layer (VikingFS, VectorDB, QueueManager)### 组件 1:PathLockEngine + LockManager + LockContext(路径锁系统)-**PathLockEngine** 实现基于文件的分布式锁,支持 EXACT 和 TREE 两种锁类型,使用 fencing token 防止 TOCTOU 竞争,自动检测并清理过期锁。+**PathLockEngine** 实现基于 Provider 的分布式锁,支持 EXACT 和 TREE 两种锁类型,使用归属 token 防止 TOCTOU 竞争,并自动检测和清理过期锁。默认 Provider 在 AGFS 中保存锁文件;Cache Provider 在 Redis 中保存 token。**LockHandle** 是轻量的锁持有者令牌:@@ -48,7 +48,7 @@ Storage Layer (VikingFS, VectorDB, QueueManager)@dataclassclass LockHandle:id: str # 唯一标识,用于生成 fencing token- locks: list[str] # 已获取的锁文件路径+ locks: list[str] # Provider handle:锁文件路径或逻辑路径created_at: float # handle 创建时间last_active_at: float # 最近一次成功 acquire/refresh 的时间```@@ -268,11 +268,11 @@ async with LockContext(lock_manager, [src], lock_mode="mv", mv_dst_path=dst):| **TREE** | 冲突 | 冲突 | 冲突 | 冲突 |- **EXACT (E)**:锁定一个具体路径本身。文件、目录名、尚未创建的目标路径都可以使用;若祖先目录持有 TreeLock 则阻塞。-- **TREE (T)**:用于删除目录、移动目录、资源生命周期保护等。逻辑上覆盖整棵子树,但只在根目录写**一个锁文件**。获取前扫描所有后代和祖先目录确认无冲突锁。目标目录不存在时,先做冲突检查;无冲突才创建目录并写锁。若创建后又发现并发冲突,本次加锁失败,但不回滚刚创建出来的空目录。+- **TREE (T)**:用于删除目录、移动目录、资源生命周期保护等。逻辑上覆盖整棵子树,但只为根路径保存一个 Provider token。冲突检查覆盖 Provider scope 内的后代和持有 Tree 锁的祖先。Filesystem Provider 可能为了写锁文件而创建尚不存在的目标目录。## 锁机制-### 锁协议+### Filesystem Provider 锁协议锁文件路径:@@ -289,7 +289,30 @@ ExactPathLock(文件或未创建路径) -> {parent}/.exact.ovlock.<name>.<hash>其中 `lock_type` 为 `E`(EXACT)或 `T`(TREE)。-### 获取锁流程(EXACT 模式)+### Cache Provider 锁协议++Cache Provider 将相同 token 格式存入 Redis HASH field,并通过 Lua+原子完成整批冲突检查和写入:++```text+field = logical_path+value = owner_id:time_ns:lock_type+```++HASH key 按路径 scope 隔离:++```text+ov:pathlock:{namespace}:global:tokens+ov:pathlock:{namespace}:scope:_system:tokens+ov:pathlock:{namespace}:scope:account:{account}:tokens+```++所有 key 都使用 `{namespace}` 作为 Redis Cluster hash tag。Exact 获取使用+`HMGET` 读取目标和祖先;Tree 获取只对所属 scope 的 HASH 执行+`HGETALL`。`/` 和 `/local` 的 global 锁不会扫描 account 或 `_system`+HASH。跨 scope batch 会被拒绝。++### Filesystem 获取锁流程(EXACT 模式)```循环直到超时(轮询间隔:200ms):@@ -311,7 +334,7 @@ ExactPathLock(文件或未创建路径) -> {parent}/.exact.ovlock.<name>.<hash>超时(默认 0 = 不等待)抛出 LockAcquisitionError```-### 获取锁流程(TREE 模式)+### Filesystem 获取锁流程(TREE 模式)```循环直到超时(轮询间隔:200ms):@@ -365,11 +388,11 @@ fencing token 校验通过的一方成功持有 `TreeLock(java-guide)`;失败### 锁过期清理-**陈旧锁检测**:PathLockEngine 检查 fencing token 中的时间戳。超过 `lock_expire`(默认 30s)的锁被视为陈旧锁,在加锁过程中自动移除。+**陈旧锁检测**:PathLockEngine 检查归属 token 中的时间戳。超过 `lock_expire`(默认 30s)的锁被视为陈旧锁,在加锁过程中自动移除。-**进程内清理**:LockManager 每 60 秒检查活跃的 LockHandle。仍持有锁文件且失活时间超过 `lock_expire` 的 handle 会被强制释放。+**进程内清理**:LockManager 每 60 秒检查活跃的 LockHandle。仍持有 Provider token 且失活时间超过 `lock_expire` 的 handle 会被强制释放。-**孤儿锁**:进程崩溃后遗留的锁文件,在下次任何操作尝试获取同一路径锁时,通过 stale lock 检测自动移除。+**孤儿锁**:进程崩溃后遗留的 Provider token,在后续 acquire 检查同一路径或 scope 时通过 stale lock 检测自动移除。## 崩溃恢复@@ -378,7 +401,7 @@ fencing token 校验通过的一方成功持有 `TreeLock(java-guide)`;失败| 场景 | 恢复方式 ||------|---------|| session_memory 提取中途崩溃 | 从 archive 恢复 Phase 2 并继续消费 `session_commit` 任务 |-| 锁持有期间崩溃 | 锁文件留在 AGFS,下次获取时 stale 检测自动清理(默认 30s 过期)|+| 锁持有期间崩溃 | Provider token 保留,后续匹配的 acquire 通过 stale 检测自动清理(默认 30s 过期)|| enqueue 后 worker 处理前崩溃 | QueueFS SQLite 持久化,worker 重启后自动拉取 || 孤儿索引 | L2 按需加载时清理 |@@ -394,7 +417,12 @@ fencing token 校验通过的一方成功持有 `TreeLock(java-guide)`;失败## 配置-路径锁默认启用,无需额外配置。推荐通过 `storage.agfs.pathlock` 配置过期时间。运行时等待超时固定为 `0.0` 秒,不再接受外部配置。`storage.transaction` 仅保留为兼容旧配置:`lock_timeout` 已废弃且会被忽略,`lock_expire` 会在未显式配置新字段时自动映射,`redo_recovery_enabled` 已废弃且会被忽略。+路径锁默认启用,并使用 `filesystem` Provider。多进程通过 Redis 协调时,+设置 `storage.agfs.pathlock.provider=cache`。Cache PathLock 要求配置顶层+Redis Cache Provider 和非空 PathLock namespace。运行时等待超时固定为+`0.0` 秒。`storage.transaction` 仅保留为兼容旧配置:`lock_timeout`+已废弃且会被忽略,`lock_expire` 会在未显式配置新字段时自动映射,+`redo_recovery_enabled` 已废弃且会被忽略。推荐写法:@@ -403,6 +431,7 @@ fencing token 校验通过的一方成功持有 `TreeLock(java-guide)`;失败"storage": {"agfs": {"pathlock": {+ "provider": "filesystem","lock_expire_secs": 30.0}}@@ -410,6 +439,35 @@ fencing token 校验通过的一方成功持有 `TreeLock(java-guide)`;失败}```+Redis 配置:++```json+{+ "cache": {+ "provider": "redis",+ "params": {+ "mode": "standalone",+ "endpoints": ["redis://127.0.0.1:6379"]+ }+ },+ "storage": {+ "agfs": {+ "pathlock": {+ "provider": "cache",+ "namespace": "production",+ "lock_expire_secs": 30.0+ }+ }+ }+}+```++| 参数 | 类型 | 说明 | 默认值 |+|------|------|------|--------|+| `provider` | str | `filesystem`、`memory` 或 `cache` | `filesystem` |+| `namespace` | str 或 null | `provider=cache` 时必填,用于标识一个 OpenViking 部署 | `null` |+| `lock_expire_secs` | float | 未刷新的锁进入 stale 状态前的秒数 | `30.0` |+兼容旧写法:```jsondiff --git a/docs/zh/guides/01-configuration.md b/docs/zh/guides/01-configuration.mdindex 385c28db0..5900e07d9 100644--- a/docs/zh/guides/01-configuration.md+++ b/docs/zh/guides/01-configuration.md@@ -1099,7 +1099,7 @@ RAGFS 默认使用 Rust binding 模式,通过 Rust 实现直接访问文件系更多配置示例见 [多写存储指南](./13-multi-write-storage.md)。-##### 全局 Cache Provider 与 CacheFS 配置+##### 全局 Cache Provider、CacheFS 与 PathLock 配置全局 `cache` 与 `storage` 并列,标准配置只包含 Provider 名称和 Provider 自有参数:@@ -1118,6 +1118,15 @@ RAGFS 默认使用 Rust binding 模式,通过 Rust 实现直接访问文件系| `traversal_mode` | str | `backend` 或 `cached_traversal` | `backend` || `bypass_prefixes` | array[str] | 绕过缓存的路径前缀 | `[]` |+`storage.agfs.pathlock` 选择 PathLock 存储 Provider:++| 参数 | 类型 | 说明 | 默认值 |+|------|------|------|--------|+| `provider` | str | `filesystem`、`memory` 或 `cache`;`cache` 复用 Redis CacheRuntime | `filesystem` |+| `namespace` | str(可选) | Redis PathLock key 使用的 OpenViking 实例名;`provider=cache` 时必填 | `null` |+| `lock_expire_secs` | float | 未刷新的锁进入 stale 状态前的秒数;不得小于 `1.0` | `30.0` |+| `lock_timeout_secs` | float | 已废弃且忽略;运行时等待超时固定为 `0.0` | `0.0` |+```json{"cache": {@@ -1143,13 +1152,18 @@ RAGFS 默认使用 Rust binding 模式,通过 Rust 实现直接访问文件系"queuefs": {"backend": "cache","cache_key_prefix": "production"+ },+ "pathlock": {+ "provider": "cache",+ "namespace": "production",+ "lock_expire_secs": 30.0}}}}```-标准配置没有全局 `cache.enabled`。当 CacheFS 或 QueueFS 选择 `backend=cache` 时初始化 CacheRuntime;全部模块使用本地 backend 时不解析 `cache.params`,也不连接 Provider。+标准配置没有全局 `cache.enabled`。当 CacheFS 或 QueueFS 选择 `backend=cache`,或 PathLock 选择 `provider=cache` 时初始化 CacheRuntime。Cache PathLock 当前只支持 `cache.provider=redis`,不支持 DynamicProvider。全部模块使用本地 Provider 时不解析 `cache.params`,也不连接 Provider。这是一次配置破坏性变更:`storage.agfs.cache`、`storage.agfs.queuefs.backend="redis"` 和 `storage.agfs.queuefs.redis` 已删除并会被拒绝。请把 Provider 参数迁移到顶层 `cache.provider/cache.params`,业务模块改为 `cachefs.backend="cache"` 或 `queuefs.backend="cache"`;Redis 的 `singleton` 改为 `standalone`,`tls_enabled` 改为使用 `rediss://` endpoint。@@ -1811,7 +1825,7 @@ openviking add-resource ./docs --exclude "*.tmp"## storage.transaction 段-`storage.transaction` 已废弃,仅保留为兼容旧配置。新配置请仅使用 `storage.agfs.pathlock` 配置过期时间。若旧字段仍然出现,OpenViking 会在运行时给出 warning;其中 `lock_timeout` 已废弃且会被忽略,`lock_expire` 会在未显式配置新字段时自动映射到新的 `pathlock` 配置,`redo_recovery_enabled` 则会被忽略。+`storage.transaction` 已废弃,仅保留为兼容旧配置。新配置请使用 `storage.agfs.pathlock` 配置 PathLock Provider、namespace 和过期时间。若旧字段仍然出现,OpenViking 会在运行时给出 warning;其中 `lock_timeout` 已废弃且会被忽略,`lock_expire` 会在未显式配置新字段时自动映射到新的 `pathlock` 配置,`redo_recovery_enabled` 则会被忽略。推荐写法:@@ -1820,6 +1834,7 @@ openviking add-resource ./docs --exclude "*.tmp""storage": {"agfs": {"pathlock": {+ "provider": "filesystem","lock_expire_secs": 30.0}}diff --git a/docs/zh/guides/14-ragfs-cache.md b/docs/zh/guides/14-ragfs-cache.mdindex a4a2a50c5..e3724e7d1 100644--- a/docs/zh/guides/14-ragfs-cache.md+++ b/docs/zh/guides/14-ragfs-cache.md@@ -2,13 +2,15 @@RAGFS 缓存是 OpenViking 的可选读缓存层,用于加速文件全量读取和目录读取。它只作为加速层,不作为事实数据源;数据仍以 backend filesystem 为准。-适用前提:+CachedFileSystem 适用前提:- 只有一个 OpenViking / RAGFS 进程写入同一 namespace。- 文件和目录变更都经过 RAGFS。- backend 不被外部绕过 RAGFS 直接修改。- 缓存 Provider 的同一 key 写入或删除成功后,后续读取不会返回旧值。+这些前提只适用于读缓存层。QueueFS 和 PathLock 也复用 CacheRuntime,但有各自的一致性规则。+## 快速开始首次配置仍建议先完成基础配置:@@ -42,6 +44,11 @@ openviking-server doctor"namespace": "openviking","max_file_size_bytes": 1048576,"bypass_prefixes": ["/queue", "/tmp"]+ },+ "pathlock": {+ "provider": "cache",+ "namespace": "openviking",+ "lock_expire_secs": 30.0}}}@@ -70,6 +77,29 @@ openviking-server`MemoryMockProvider` 只用于单元测试和 smoke test,不是生产配置项。+### Cache PathLock++将 `storage.agfs.pathlock.provider` 设为 `cache`,即可通过共享 Redis+CacheRuntime 协调多个 OpenViking 进程的路径锁。`pathlock.namespace`+为必填项,同一 OpenViking 部署的所有进程必须使用相同值。Cache PathLock+只支持内置 Redis Provider。++Redis HASH key 按逻辑路径 scope 拆分:++```text+ov:pathlock:{namespace}:global:tokens+ov:pathlock:{namespace}:scope:_system:tokens+ov:pathlock:{namespace}:scope:account:{account}:tokens+```++`{namespace}` 是 Redis Cluster hash tag,因此同一部署的 PathLock key+仍位于同一 slot。Tree 冲突检查只扫描请求所属 scope 的 HASH。`/` 和+`/local` 使用 global HASH,但不会扫描 account 或 `_system` HASH。+跨 scope batch 会被拒绝。++不要混部仍使用旧单 HASH key 的版本和使用 scope key 的版本。先停止旧版本+写入,至少等待 `2 * lock_expire_secs` 让旧 key 过期,再启动新版本。+## 配置破坏性变更旧缓存配置不再兼容,升级前需要完成迁移:@@ -120,6 +150,14 @@ Provider 发布物应注明 ABI 版本、目标 OS/CPU、最低运行时版本| `traversal_mode` | str | `"backend"` | 递归 API 使用 backend 遍历或 `cached_traversal` || `bypass_prefixes` | list[str] | `[]` | 强制绕过缓存的路径前缀 |+`storage.agfs.pathlock` 控制 PathLock 存储:++| 参数 | 类型 | 默认值 | 说明 |+|------|------|--------|------|+| `provider` | str | `"filesystem"` | `filesystem`、`memory` 或 `cache` |+| `namespace` | str 或 null | `null` | `provider=cache` 时必填的 OpenViking 实例名 |+| `lock_expire_secs` | float | `30.0` | 锁 stale 超时;不得小于 `1.0` |+Redis 配置:| 参数 | 默认值 | 说明 |@@ -155,23 +193,27 @@ DynamicProvider 配置:## 整体架构-RAGFS 将缓存拆成两层:+RAGFS 将 Provider 访问和各业务消费者分开:- `CachedFileSystem`:实现文件系统语义,包括 cache hit/miss、backend 回源、回填、失效、generation 校验和指标。- `CacheRuntime`:向业务层提供统一基础操作,启动时绑定内置 RedisProvider 或外部 DynamicProvider。+- `QueueFS` 和 `RedisPathLockProvider`:复用共享 CacheRuntime 存储队列和分布式锁。RedisPathLockProvider 要求使用内置 RedisProvider。调用关系:```textOpenViking-> RAGFS / MountableFS- -> CachedFileSystem- |-> CacheRuntime -> RedisProvider- | `-> DynamicProvider -> 外部动态库+ |-> CachedFileSystem ------\+ |-> QueueFS cache backend --+-> shared CacheRuntime -> RedisProvider+ `-> RedisPathLockProvider --/ `-> DynamicProvider`-> Backend FileSystem```-这种边界让文件、目录、rename、递归删除和写后失效逻辑只在公共层实现。外部 Provider 不需要理解路径语义,只需要通过稳定 C ABI 提供 key-value 基础操作。+CachedFileSystem 和 QueueFS 可以使用 RedisProvider 或 DynamicProvider。+RedisPathLockProvider 依赖 Redis Lua,因此只使用 RedisProvider。文件系统语义+保留在 CachedFileSystem;外部 Provider 只通过稳定 C ABI 提供 key-value+基础操作。## 缓存对象diff --git a/openviking/storage/queuefs/semantic_lock.py b/openviking/storage/queuefs/semantic_lock.pyindex cd82e96d2..4f1cfa8e9 100644--- a/openviking/storage/queuefs/semantic_lock.py+++ b/openviking/storage/queuefs/semantic_lock.py@@ -18,7 +18,7 @@ _TREE_LOCK_SUFFIX = f"/{MULTIWRITE_PATH_LOCK_FILE}"def _tree_paths_from_handoff(lock_paths: Iterable[str]) -> list[str]:- """Extract tree lock directory paths from lock file paths."""+ """Extract tree lock directory paths from legacy lock file handles."""tree_paths: list[str] = []for lock_path in lock_paths:if not lock_path.endswith(_TREE_LOCK_SUFFIX):@@ -44,7 +44,7 @@ class SemanticLockScope:caller_lock: Optional[Dict[str, Any]] = None,fallback_path_factory: Optional[Callable[[], str]] = None,) -> "SemanticLockScope":- """Resolve a live lock, lazily deriving a path for stale legacy handoffs."""+ """Resolve a live lock, reacquiring its original coverage when stale."""if lock_handoff and caller_lock is not None:raise ValueError("semantic lock must come from either message or caller, not both")if caller_lock is not None:@@ -54,22 +54,29 @@ class SemanticLockScope:viking_fs = get_viking_fs()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"])- if not tree_paths and fallback_path_factory:- tree_paths = [fallback_path_factory()]- if not tree_paths:+ except LockAcquisitionError as error:+ # ponytail: Replace this message check with a recoverable handoff+ # exception when the native binding exposes typed handoff failures.+ error_message = str(error)+ if "is no longer owned by" not in error_message and (+ "logical-path provider handoff requires covered_paths" not in error_message+ ):raise+ covered_paths = lock_handoff.get("covered_paths") or []+ if not covered_paths:+ 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+ covered_paths = [{"path": path, "kind": "tree"} for path in tree_paths]- if len(tree_paths) == 1:- lease = await viking_fs._async_agfs.pathlock_acquire_tree(tree_paths[0])- else:- lease = await viking_fs._async_agfs.pathlock_acquire_tree_batch(tree_paths)+ lease = await viking_fs._async_agfs.pathlock_acquire_batch(covered_paths)logger.info("Recovered semantic lock handoff %s by reacquiring %s",lock_handoff.get("owner_id"),- tree_paths,+ covered_paths,)return cls(lease, _owned=True)return cls(None)diff --git a/openviking/utils/agfs_utils.py b/openviking/utils/agfs_utils.pyindex 06b677e69..6f6fc7b83 100644--- a/openviking/utils/agfs_utils.py+++ b/openviking/utils/agfs_utils.py@@ -39,7 +39,15 @@ class RagfsBindingConfig:queue_backend = getattr(queuefs, "backend", None)cachefs = getattr(self.agfs, "cachefs", None)cachefs_backend = getattr(cachefs, "backend", "local")- uses_runtime = cachefs_backend == "cache" or queue_backend == "cache"+ pathlock = self.agfs.pathlock.model_dump(mode="json", exclude_none=True)+ pathlock_uses_cache = pathlock.get("provider") == "cache"+ uses_runtime = cachefs_backend == "cache" or queue_backend == "cache" or pathlock_uses_cache+ if (+ pathlock_uses_cache+ and self.cache is not None+ and self.cache.provider.strip() != "redis"+ ):+ raise ValueError("cache-backed PathLock requires top-level cache.provider=redis")if self.cache is not None and uses_runtime:cache_config = _build_provider_cache_config(self.cache,@@ -52,12 +60,13 @@ class RagfsBindingConfig:else:if uses_runtime:raise ValueError(- "top-level cache config is required when CacheFS or QueueFS uses backend=cache"+ "top-level cache config is required when CacheFS, QueueFS, or cache-backed PathLock "+ "uses the shared Runtime")cache_config = _disabled_cache_config(cachefs)binding_config: Dict[str, Any] = {"cache": cache_config,- "pathlock": self.agfs.pathlock.model_dump(mode="json"),+ "pathlock": pathlock,}if self.log is not None:diff --git a/openviking_cli/utils/config/agfs_config.py b/openviking_cli/utils/config/agfs_config.pyindex 4d40dc075..56479d2e6 100644--- a/openviking_cli/utils/config/agfs_config.py+++ b/openviking_cli/utils/config/agfs_config.py@@ -2,6 +2,7 @@# SPDX-License-Identifier: AGPL-3.0from __future__ import annotations+import mathfrom enum import Enumfrom typing import Any, List, Literal, Optionalfrom urllib.parse import urlparse@@ -317,7 +318,11 @@ class AGFSPathLockConfig(BaseModel):provider: str = Field(default="filesystem",- description="PathLock provider: 'filesystem' | 'memory'",+ description="PathLock provider: 'filesystem' | 'memory' | 'cache'",+ )+ namespace: Optional[str] = Field(+ default=None,+ description="OpenViking instance name used by cache-backed PathLock.",)lock_timeout_secs: float = Field(default=0.0,@@ -333,10 +338,22 @@ class AGFSPathLockConfig(BaseModel):@model_validator(mode="after")def validate_config(self):"""Validate provider and timeout/expiry ranges."""- 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")+ if self.provider not in {"filesystem", "memory", "cache"}:+ raise ValueError("pathlock provider must be one of: 'filesystem', 'memory', 'cache'")+ if self.provider == "cache" and not (self.namespace or "").strip():+ raise ValueError("pathlock namespace is required for provider 'cache'")+ if self.namespace is not None and (+ not self.namespace+ or any(+ not (char.isascii() and (char.isalnum() or char in "._-"))+ for char in self.namespace+ )+ ):+ raise ValueError(+ "pathlock namespace must contain only ASCII letters, digits, '.', '_' or '-'"+ )+ if not math.isfinite(self.lock_expire_secs) or self.lock_expire_secs < 1.0:+ raise ValueError("pathlock lock_expire_secs must be finite and >= 1.0")return selfdiff --git a/tests/misc/test_config_validation.py b/tests/misc/test_config_validation.pyindex 7a24ec966..ad6bf3a6c 100644--- a/tests/misc/test_config_validation.py+++ b/tests/misc/test_config_validation.py@@ -390,9 +390,7 @@ def test_rediss_scheme_enables_tls_without_boolean_flag():binding = RagfsBindingConfig(config.storage.agfs, cache=config.cache).to_binding_dict()- assert binding["cache"]["redis"]["endpoints"] == [- "rediss://redis.example.com:6380"- ]+ assert binding["cache"]["redis"]["endpoints"] == ["rediss://redis.example.com:6380"]assert "tls_enabled" not in binding["cache"]["redis"]@@ -730,22 +728,67 @@ def test_ragfs_binding_enables_runtime_for_queuefs_cache_backend(tmp_path):def test_agfs_pathlock_config_validates_provider_and_expiry(tmp_path):- """PathLock config accepts built-ins and rejects unsafe expiry values."""+ """PathLock config validates Redis namespace and expiry boundaries."""config = AGFSConfig(path=str(tmp_path),backend="local",- pathlock={"provider": "memory", "lock_expire_secs": 60.0},+ pathlock={+ "provider": "cache",+ "namespace": "prod-a",+ "lock_expire_secs": 60.0,+ },)- assert config.pathlock.provider == "memory"+ assert config.pathlock.provider == "cache"+ assert config.pathlock.namespace == "prod-a"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="namespace"):+ AGFSConfig(path=str(tmp_path), pathlock={"provider": "cache"})+ with pytest.raises(ValueError, match="namespace"):+ AGFSConfig(+ path=str(tmp_path),+ pathlock={"provider": "cache", "namespace": "bad{name}"},+ )with pytest.raises(ValueError, match="lock_expire_secs"):AGFSConfig(path=str(tmp_path), pathlock={"lock_expire_secs": 0.0})+def test_redis_pathlock_enables_shared_runtime_without_cachefs(tmp_path):+ """Redis PathLock alone should enable the configured Redis Runtime."""+ config = OpenVikingConfig.from_dict(+ {+ "cache": {+ "provider": "redis",+ "params": {"endpoints": ["redis://redis:6379"]},+ },+ "storage": {+ "workspace": str(tmp_path),+ "agfs": {+ "pathlock": {+ "provider": "cache",+ "namespace": "prod-a",+ }+ },+ },+ }+ )++ binding = RagfsBindingConfig(+ agfs=config.storage.agfs,+ cache=config.cache,+ ).to_binding_dict()++ assert binding["cache"]["enabled"] is False+ assert binding["cache"]["runtime_enabled"] is True+ assert binding["pathlock"] == {+ "provider": "cache",+ "namespace": "prod-a",+ "lock_expire_secs": 30.0,+ "lock_timeout_secs": 0.0,+ }++def test_create_agfs_client_uses_single_binding_config_object(monkeypatch, tmp_path):agfs_config = AGFSConfig(path=str(tmp_path),