Skip to content

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

feat(pathlock): pathlock support cache runtime (#4918)

baojun-zhang35c984c449d1
diff --git a/crates/ragfs-python/src/lib.rs b/crates/ragfs-python/src/lib.rs
index 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, &params, "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, &params)?;
}
}
@@ -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.rs
index 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.rs
index 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.rs
new file mode 100644
index 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(&current)),
+ 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.rs
index 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.rs
index 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.rs
index 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.md
index 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)
@dataclass
class 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 paths
created_at: float # Handle creation time
last_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 Protocol
Lock 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:
```json
diff --git a/docs/en/guides/01-configuration.md b/docs/en/guides/01-configuration.md
index 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 Configuration
The 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.md
index 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 Start
For 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 Change
Legacy 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:
```text
OpenViking
-> 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 Objects
diff --git a/docs/zh/concepts/09-transaction.md b/docs/zh/concepts/09-transaction.md
index 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)
@dataclass
class 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` |
+
兼容旧写法:
```json
diff --git a/docs/zh/guides/01-configuration.md b/docs/zh/guides/01-configuration.md
index 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.md
index 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。
调用关系:
```text
OpenViking
-> 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.py
index 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.py
index 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.py
index 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.0
from __future__ import annotations
+import math
from enum import Enum
from typing import Any, List, Literal, Optional
from 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 self
diff --git a/tests/misc/test_config_validation.py b/tests/misc/test_config_validation.py
index 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),