Skip to content

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

feat(cache): 增加顶层 service_name 配置, 删除 namespace/cache_key_prefix ,使用service_name 统一管理 (#6011)

baojun-zhang6c1107527af4
diff --git a/crates/ragfs-python/src/lib.rs b/crates/ragfs-python/src/lib.rs
index b09adc8c8..c415e33bf 100644
--- a/crates/ragfs-python/src/lib.rs
+++ b/crates/ragfs-python/src/lib.rs
@@ -296,7 +296,7 @@ struct RagfsCacheConfig {
enabled: bool,
runtime_enabled: bool,
provider: CacheProviderKind,
- namespace: String,
+ service_name: String,
max_file_size_bytes: usize,
traversal_mode: CacheTraversalMode,
bypass_prefixes: Vec<String>,
@@ -345,7 +345,7 @@ impl Default for RagfsCacheConfig {
enabled: false,
runtime_enabled: false,
provider: CacheProviderKind::Redis,
- namespace: "openviking".to_string(),
+ service_name: String::new(),
max_file_size_bytes: CachePolicy::default().max_file_size(),
traversal_mode: CacheTraversalMode::Backend,
bypass_prefixes: Vec::new(),
@@ -421,7 +421,7 @@ impl RagfsCacheConfig {
provider: Some(provider),
cachefs: CacheFsConfig {
enabled: self.enabled,
- namespace: self.namespace.clone(),
+ service_name: self.service_name.clone(),
policy: cache_policy_from_config(self),
},
})
@@ -429,39 +429,38 @@ impl RagfsCacheConfig {
}
/// Load PathLock configuration from one canonical OpenViking config file.
-fn pathlock_config_from_ov_conf(path: &str) -> Result<PathLockConfig, String> {
+fn pathlock_config_from_ov_conf(path: &str, service_name: &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)
+ pathlock_config_from_canonical_ov_conf(&json, service_name)
}
/// Parse PathLock configuration from the canonical `storage.agfs.pathlock` section.
fn pathlock_config_from_canonical_ov_conf(
json: &serde_json::Value,
+ service_name: &str,
) -> 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),
+ Some(pathlock) => pathlock_config_from_value(pathlock, service_name),
None => Ok(PathLockConfig::default()),
}
}
/// Parse one sectioned PathLock configuration object.
-fn pathlock_config_from_value(value: &serde_json::Value) -> Result<PathLockConfig, String> {
+fn pathlock_config_from_value(
+ value: &serde_json::Value,
+ service_name: &str,
+) -> 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",
- ];
+ const FIELDS: &[&str] = &["provider", "lock_timeout_secs", "lock_expire_secs"];
if let Some(field) = pathlock
.keys()
.find(|field| !FIELDS.contains(&field.as_str()))
@@ -475,21 +474,7 @@ fn pathlock_config_from_value(value: &serde_json::Value) -> Result<PathLockConfi
"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 pathlock_service_name = (provider == "cache").then(|| service_name.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 {
@@ -502,43 +487,58 @@ fn pathlock_config_from_value(value: &serde_json::Value) -> Result<PathLockConfi
Ok(PathLockConfig {
provider,
- namespace,
+ service_name: pathlock_service_name,
lock_timeout_secs,
lock_expire_secs,
})
}
-fn cache_config_from_ov_conf(path: &str) -> Result<RagfsCacheConfig, String> {
+fn cache_config_from_ov_conf(path: &str, service_name: &str) -> 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(&json)
+ cache_config_from_canonical_ov_conf(&json, service_name)
}
/// Load canonical cache configuration while forcing a shared Runtime consumer.
fn cache_config_from_ov_conf_with_runtime(
path: &str,
force_runtime: bool,
+ service_name: &str,
) -> 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)
+ cache_config_from_canonical_ov_conf_with_runtime(&json, force_runtime, service_name)
}
fn cache_config_from_canonical_ov_conf(
json: &serde_json::Value,
+ service_name: &str,
) -> 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)
+ let pathlock_uses_cache =
+ pathlock_config_from_canonical_ov_conf(json, service_name)?.provider == "cache";
+ let backups_use_cache = json
+ .get("storage")
+ .and_then(|storage| storage.get("agfs"))
+ .and_then(|agfs| agfs.get("backups"))
+ .and_then(|backups| backups.get("provider"))
+ .and_then(serde_json::Value::as_str)
+ == Some("cache");
+ cache_config_from_canonical_ov_conf_with_runtime(
+ json,
+ pathlock_uses_cache || backups_use_cache,
+ service_name,
+ )
}
/// 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,
+ service_name: &str,
) -> Result<RagfsCacheConfig, String> {
let agfs = json.get("storage").and_then(|storage| storage.get("agfs"));
if agfs.and_then(|agfs| agfs.get("cache")).is_some() {
@@ -573,13 +573,13 @@ fn cache_config_from_canonical_ov_conf_with_runtime(
}
let mut config = RagfsCacheConfig::default();
+ config.service_name = service_name.to_string();
config.enabled = cachefs_backend == "cache";
config.runtime_enabled = config.enabled || queuefs_backend == "cache" || force_runtime;
if let Some(cachefs) = cachefs {
let cachefs = cachefs
.as_object()
.ok_or_else(|| "storage.agfs.cachefs must be an object".to_string())?;
- config.namespace = string_field(cachefs, "namespace", &config.namespace)?;
config.max_file_size_bytes =
usize_field(cachefs, "max_file_size_bytes", config.max_file_size_bytes)?;
config.traversal_mode =
@@ -593,7 +593,7 @@ fn cache_config_from_canonical_ov_conf_with_runtime(
let cache = json
.get("cache")
.ok_or_else(|| {
- "top-level cache.provider/cache.params is required when CacheFS or QueueFS uses backend=cache"
+ "top-level cache.provider/cache.params is required when AGFS uses cache-backed modules"
.to_string()
})?
.as_object()
@@ -642,23 +642,25 @@ fn optional_backend(
string_field(section, "backend", default)
}
-fn cache_config_from_value(cache: &serde_json::Value) -> Result<RagfsCacheConfig, String> {
+fn cache_config_from_value(
+ cache: &serde_json::Value,
+ service_name: &str,
+) -> Result<RagfsCacheConfig, String> {
if cache.is_null() {
- return Ok(RagfsCacheConfig::default());
+ let mut config = RagfsCacheConfig::default();
+ config.service_name = service_name.to_string();
+ return Ok(config);
}
let cache = cache
.as_object()
.ok_or_else(|| "binding cache config must be an object".to_string())?;
let mut config = RagfsCacheConfig::default();
+ config.service_name = service_name.to_string();
config.enabled = bool_field(cache, "enabled", config.enabled)?;
config.runtime_enabled = bool_field(cache, "runtime_enabled", config.enabled)?;
let provider = string_field(cache, "provider", "redis")?;
config.provider = provider_kind(provider)?;
- config.namespace = string_field(cache, "namespace", &config.namespace)?;
- if config.namespace.trim().is_empty() {
- return Err("cache.namespace must not be empty".to_string());
- }
config.max_file_size_bytes =
usize_field(cache, "max_file_size_bytes", config.max_file_size_bytes)?;
config.traversal_mode = traversal_mode(string_field(cache, "traversal_mode", "backend")?)?;
@@ -1504,7 +1506,8 @@ impl RAGFSBindingClient {
impl RAGFSBindingClient {
/// Create a new RAGFS binding client.
///
- /// `config_path` loads the canonical ov.conf schema. Removed cache schemas are rejected.
+ /// `config_path` loads the canonical ov.conf schema. `config.service_name` must be supplied
+ /// by the Python runtime.
/// `config` is an optional sectioned dict produced by the Python runtime. The `encryption`
/// section, when present, carries `root_key` (32 bytes) + `provider_type` (int) and causes the
/// stack to include an `EncryptionWrappedFS` layer. Runtime `cache` configuration takes
@@ -1522,19 +1525,34 @@ impl RAGFSBindingClient {
// Phase A (holding GIL): parse the sectioned config into an owned RagfsConfig.
let mut ragfs_cfg = RagfsConfig::default();
+ let service_name = match config.as_ref() {
+ Some(cfg) => Some(
+ cfg.get("service_name")
+ .ok_or_else(|| PyValueError::new_err("service_name is required"))?
+ .extract::<String>(py)?,
+ ),
+ None => None,
+ };
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 service_name = service_name
+ .as_deref()
+ .ok_or_else(|| PyValueError::new_err("service_name is required"))?;
+ ragfs_cfg.pathlock =
+ pathlock_config_from_ov_conf(path, service_name).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 {
+ let service_name = service_name
+ .as_deref()
+ .ok_or_else(|| PyValueError::new_err("service_name is required"))?;
if let Some(log_obj) = cfg.get("log") {
let log_cfg: HashMap<String, Py<PyAny>> = log_obj.extract(py)?;
let log_level = log_cfg
@@ -1570,10 +1588,11 @@ impl RAGFSBindingClient {
}
if let Some(cache_obj) = cfg.get("cache") {
let cache_value = py_to_json_value(cache_obj.bind(py))?;
- runtime_cache_config =
- Some(cache_config_from_value(&cache_value).map_err(|error| {
+ runtime_cache_config = Some(
+ cache_config_from_value(&cache_value, service_name).map_err(|error| {
PyRuntimeError::new_err(format!("Invalid cache config: {error}"))
- })?);
+ })?,
+ );
}
if let Some(git_obj) = cfg.get("git") {
let git_value = py_to_json_value(git_obj.bind(py))?;
@@ -1583,8 +1602,8 @@ impl RAGFSBindingClient {
}
if let Some(pl_obj) = cfg.get("pathlock") {
let pl_value = py_to_json_value(pl_obj.bind(py))?;
- ragfs_cfg.pathlock =
- pathlock_config_from_value(&pl_value).map_err(PyValueError::new_err)?;
+ ragfs_cfg.pathlock = pathlock_config_from_value(&pl_value, service_name)
+ .map_err(PyValueError::new_err)?;
}
}
@@ -1592,12 +1611,15 @@ impl RAGFSBindingClient {
let pathlock_uses_cache = ragfs_cfg.pathlock.provider == "cache";
let file_cache_config = config_path
.map(|path| {
+ let service_name = service_name
+ .as_deref()
+ .ok_or_else(|| "service_name is required".to_string())?;
if inline_cache_configured {
- cache_config_from_ov_conf_with_runtime(path, false)
+ cache_config_from_ov_conf_with_runtime(path, false, service_name)
} else if inline_pathlock_configured {
- cache_config_from_ov_conf_with_runtime(path, pathlock_uses_cache)
+ cache_config_from_ov_conf_with_runtime(path, pathlock_uses_cache, service_name)
} else {
- cache_config_from_ov_conf(path)
+ cache_config_from_ov_conf(path, service_name)
}
})
.transpose()
@@ -3100,19 +3122,27 @@ mod tests {
}
#[test]
- fn constructor_accepts_canonical_config_path() {
+ fn constructor_accepts_canonical_config_path_with_runtime_service_name() {
let path = std::env::temp_dir().join(format!(
"openviking-canonical-config-path-{}.json",
std::process::id()
));
- fs::write(&path, r#"{"storage": {"agfs": {"backend": "local"}}}"#).unwrap();
+ fs::write(
+ &path,
+ r#"{"service_name": "test-service", "storage": {"agfs": {"backend": "local"}}}"#,
+ )
+ .unwrap();
+ Python::initialize();
Python::attach(|py| {
let ty = py.get_type::<RAGFSBindingClient>();
+ let config = PyDict::new(py);
+ config.set_item("service_name", "test-service").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());
});
@@ -3130,6 +3160,7 @@ mod tests {
fs::write(
&path,
r#"{
+ "service_name": "test-service",
"storage": {
"agfs": {
"pathlock": {"provider": "cache"}
@@ -3144,6 +3175,7 @@ mod tests {
let pathlock = PyDict::new(py);
pathlock.set_item("provider", "filesystem").unwrap();
let config = PyDict::new(py);
+ config.set_item("service_name", "inline-prod").unwrap();
config.set_item("pathlock", pathlock).unwrap();
let kwargs = PyDict::new(py);
kwargs
@@ -3168,7 +3200,11 @@ mod tests {
"openviking-inline-redis-pathlock-{}.json",
std::process::id()
));
- fs::write(&path, r#"{"storage": {"agfs": {"backend": "local"}}}"#).unwrap();
+ fs::write(
+ &path,
+ r#"{"service_name": "test-service", "storage": {"agfs": {"backend": "local"}}}"#,
+ )
+ .unwrap();
Python::attach(|py| {
let ty = py.get_type::<RAGFSBindingClient>();
@@ -3182,9 +3218,9 @@ mod tests {
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("service_name", "inline-prod").unwrap();
config.set_item("cache", cache).unwrap();
config.set_item("pathlock", pathlock).unwrap();
let kwargs = PyDict::new(py);
@@ -3248,13 +3284,18 @@ mod tests {
"openviking-no-cache-config-{}.json",
std::process::id()
));
- fs::write(&path, r#"{"storage": {"agfs": {"backend": "local"}}}"#).unwrap();
+ fs::write(
+ &path,
+ r#"{"service_name": "test-service", "storage": {"agfs": {"backend": "local"}}}"#,
+ )
+ .unwrap();
- let cache_config = cache_config_from_ov_conf(path.to_str().unwrap()).unwrap();
+ let cache_config =
+ cache_config_from_ov_conf(path.to_str().unwrap(), "test-service").unwrap();
assert!(!cache_config.enabled);
assert_eq!(cache_config.provider, CacheProviderKind::Redis);
- assert_eq!(cache_config.namespace, "openviking");
+ assert_eq!(cache_config.service_name, "test-service");
assert_eq!(cache_config.traversal_mode, CacheTraversalMode::Backend);
fs::remove_file(path).unwrap();
@@ -3269,6 +3310,7 @@ mod tests {
fs::write(
&path,
r#"{
+ "service_name": "prod-a",
"cache": {
"provider": "redis",
"params": {"endpoints": ["redis://redis:6379"]}
@@ -3277,7 +3319,6 @@ mod tests {
"agfs": {
"pathlock": {
"provider": "cache",
- "namespace": "prod-a",
"lock_expire_secs": 60.0
}
}
@@ -3286,11 +3327,11 @@ mod tests {
)
.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();
+ let pathlock = pathlock_config_from_ov_conf(path.to_str().unwrap(), "prod-a").unwrap();
+ let cache = cache_config_from_ov_conf(path.to_str().unwrap(), "prod-a").unwrap();
assert_eq!(pathlock.provider, "cache");
- assert_eq!(pathlock.namespace.as_deref(), Some("prod-a"));
+ assert_eq!(pathlock.service_name.as_deref(), Some("prod-a"));
assert_eq!(pathlock.lock_expire_secs, 60.0);
assert!(cache.runtime_enabled);
assert_eq!(cache.provider, CacheProviderKind::Redis);
@@ -3300,17 +3341,21 @@ mod tests {
}
#[test]
- fn redis_pathlock_config_requires_namespace() {
- let error = pathlock_config_from_canonical_ov_conf(&serde_json::json!({
- "storage": {
- "agfs": {
- "pathlock": {"provider": "cache"}
+ fn redis_pathlock_config_uses_runtime_service_name() {
+ let pathlock = pathlock_config_from_canonical_ov_conf(
+ &serde_json::json!({
+ "service_name": "prod-a",
+ "storage": {
+ "agfs": {
+ "pathlock": {"provider": "cache"}
+ }
}
- }
- }))
- .unwrap_err();
+ }),
+ "prod-a",
+ )
+ .unwrap();
- assert!(error.contains("namespace"));
+ assert_eq!(pathlock.service_name.as_deref(), Some("prod-a"));
}
#[test]
@@ -3322,6 +3367,7 @@ mod tests {
fs::write(
&path,
r#"{
+ "service_name": "tenant-a",
"cache": {
"provider": "redis",
"params": {
@@ -3335,7 +3381,6 @@ mod tests {
"agfs": {
"cachefs": {
"backend": "cache",
- "namespace": "tenant-a",
"traversal_mode": "cached_traversal"
},
"queuefs": {"backend": "cache"}
@@ -3345,12 +3390,12 @@ mod tests {
)
.unwrap();
- let cache_config = cache_config_from_ov_conf(path.to_str().unwrap()).unwrap();
+ let cache_config = cache_config_from_ov_conf(path.to_str().unwrap(), "tenant-a").unwrap();
assert!(cache_config.enabled);
assert!(cache_config.runtime_enabled);
assert_eq!(cache_config.provider, CacheProviderKind::Redis);
- assert_eq!(cache_config.namespace, "tenant-a");
+ assert_eq!(cache_config.service_name, "tenant-a");
assert_eq!(
cache_config.traversal_mode,
CacheTraversalMode::CachedTraversal
@@ -3368,9 +3413,13 @@ mod tests {
"openviking-removed-cache-config-{}.json",
std::process::id()
));
- fs::write(&path, r#"{"storage":{"agfs":{"cache":{"enabled":true}}}}"#).unwrap();
+ fs::write(
+ &path,
+ r#"{"service_name":"test-service","storage":{"agfs":{"cache":{"enabled":true}}}}"#,
+ )
+ .unwrap();
- let error = cache_config_from_ov_conf(path.to_str().unwrap()).unwrap_err();
+ let error = cache_config_from_ov_conf(path.to_str().unwrap(), "test-service").unwrap_err();
assert!(error.contains("storage.agfs.cache has been removed"));
assert!(error.contains("cache.provider"));
@@ -3390,7 +3439,7 @@ mod tests {
)
.unwrap();
- let error = cache_config_from_ov_conf(path.to_str().unwrap()).unwrap_err();
+ let error = cache_config_from_ov_conf(path.to_str().unwrap(), "test-service").unwrap_err();
assert!(error.contains("queuefs backend=redis has been removed"));
assert!(error.contains("backend=cache"));
@@ -3407,6 +3456,7 @@ mod tests {
fs::write(
&path,
r#"{
+ "service_name": "test-service",
"cache": {"provider": "redis", "params": {}},
"storage": {
"agfs": {
@@ -3417,7 +3467,7 @@ mod tests {
)
.unwrap();
- let cache_config = cache_config_from_ov_conf(path.to_str().unwrap()).unwrap();
+ let cache_config = cache_config_from_ov_conf(path.to_str().unwrap(), "test-service").unwrap();
let stack_config = cache_config.stack_config().unwrap();
assert!(cache_config.runtime_enabled);
@@ -3435,6 +3485,7 @@ mod tests {
fs::write(
&path,
r#"{
+ "service_name": "test-service",
"cache": {
"provider": "redis",
"params": {"key_prefix": "provider-prefix"}
@@ -3448,7 +3499,7 @@ mod tests {
)
.unwrap();
- let error = cache_config_from_ov_conf(path.to_str().unwrap()).unwrap_err();
+ let error = cache_config_from_ov_conf(path.to_str().unwrap(), "test-service").unwrap_err();
assert!(error.contains("key_prefix"));
@@ -3464,6 +3515,7 @@ mod tests {
fs::write(
&path,
r#"{
+ "service_name": "test-service",
"cache": {"provider": "mooncake", "params": {}},
"storage": {
"agfs": {
@@ -3474,7 +3526,7 @@ mod tests {
)
.unwrap();
- let error = cache_config_from_ov_conf(path.to_str().unwrap()).unwrap_err();
+ let error = cache_config_from_ov_conf(path.to_str().unwrap(), "test-service").unwrap_err();
assert!(error.contains("mooncake"));
@@ -3490,7 +3542,7 @@ mod tests {
"provider": provider,
});
- let error = cache_config_from_value(&config).unwrap_err();
+ let error = cache_config_from_value(&config, "runtime-prod").unwrap_err();
assert!(error.contains(provider));
}
@@ -3505,6 +3557,7 @@ mod tests {
fs::write(
&path,
r#"{
+ "service_name": "test-service",
"cache": {"provider": "redis", "params": {}},
"storage": {"agfs": {"cachefs": {
"backend": "cache",
@@ -3514,7 +3567,7 @@ mod tests {
)
.unwrap();
- let error = cache_config_from_ov_conf(path.to_str().unwrap()).unwrap_err();
+ let error = cache_config_from_ov_conf(path.to_str().unwrap(), "test-service").unwrap_err();
assert!(error.contains("traversal_mode"));
@@ -3531,6 +3584,7 @@ mod tests {
fs::write(
&path,
r#"{
+ "service_name": "test-service",
"cache": {"provider": "redis", "params": {}},
"storage": {"agfs": {"cachefs": {"backend": "cache"}}}
}"#,
@@ -3542,8 +3596,8 @@ mod tests {
let cache = PyDict::new(py);
cache.set_item("enabled", false).unwrap();
cache.set_item("provider", "redis").unwrap();
- cache.set_item("namespace", "runtime-cache").unwrap();
let config = PyDict::new(py);
+ config.set_item("service_name", "runtime-cache").unwrap();
config.set_item("cache", cache).unwrap();
let kwargs = PyDict::new(py);
kwargs
@@ -3567,7 +3621,7 @@ mod tests {
));
fs::write(
&path,
- r#"{"storage": {"agfs": {"cache": {"enabled": false}}}}"#,
+ r#"{"service_name": "test-service", "storage": {"agfs": {"cache": {"enabled": false}}}}"#,
)
.unwrap();
@@ -3578,6 +3632,7 @@ mod tests {
cache.set_item("runtime_enabled", false).unwrap();
cache.set_item("provider", "redis").unwrap();
let config = PyDict::new(py);
+ config.set_item("service_name", "runtime-cache").unwrap();
config.set_item("cache", cache).unwrap();
let kwargs = PyDict::new(py);
kwargs
@@ -3603,6 +3658,7 @@ mod tests {
&path,
format!(
r#"{{
+ "service_name": "test-service",
"cache": {{"provider": "redis", "params": {{"{field}": true}}}},
"storage": {{"agfs": {{"cachefs": {{"backend": "cache"}}}}}}
}}"#
@@ -3610,7 +3666,7 @@ mod tests {
)
.unwrap();
- let error = cache_config_from_ov_conf(path.to_str().unwrap()).unwrap_err();
+ let error = cache_config_from_ov_conf(path.to_str().unwrap(), "test-service").unwrap_err();
assert!(error.contains(field));
fs::remove_file(path).unwrap();
diff --git a/crates/ragfs/src/core/builder.rs b/crates/ragfs/src/core/builder.rs
index 4c5f4b67c..5fcb858d6 100644
--- a/crates/ragfs/src/core/builder.rs
+++ b/crates/ragfs/src/core/builder.rs
@@ -79,8 +79,8 @@ pub enum CacheRuntimeProviderConfig {
pub struct CacheFsConfig {
/// Whether mounted data filesystems are wrapped by CachedFileSystem.
pub enabled: bool,
- /// CacheFS key namespace.
- pub namespace: String,
+ /// OpenViking instance name used by CacheFS keys.
+ pub service_name: String,
/// Existing CacheFS policy and traversal settings.
pub policy: CachePolicy,
}
@@ -90,7 +90,7 @@ impl Default for CacheFsConfig {
fn default() -> Self {
Self {
enabled: false,
- namespace: "openviking".into(),
+ service_name: String::new(),
policy: CachePolicy::default(),
}
}
@@ -156,11 +156,12 @@ pub async fn build_configured_stack(
.to_string(),
));
}
- if pathlock_uses_cache
- && !matches!(
- &cache.provider,
- Some(CacheRuntimeProviderConfig::Redis(_))
- )
+ if cache.cachefs.enabled && cache.cachefs.service_name.trim().is_empty() {
+ return Err(Error::config(
+ "cachefs service_name is required when CacheFS 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(),
@@ -197,7 +198,7 @@ pub async fn build_configured_stack(
.as_ref()
.expect("cache provider is validated")
.clone(),
- CacheNamespace::new(&cache.cachefs.namespace),
+ CacheNamespace::new(&cache.cachefs.service_name),
cache.cachefs.policy,
))
} else if let Some(runtime) = runtime.as_ref() {
@@ -237,18 +238,14 @@ async fn build_stack_with_mountable_and_runtime(
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())
+ let service_name = config.pathlock.service_name.as_deref().ok_or_else(|| {
+ Error::config("pathlock service_name 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}"))
- })?,
+ RedisPathLockProvider::new(runtime, service_name, config.pathlock.lock_expire_secs)
+ .map_err(|error| {
+ Error::config(format!("Redis PathLock initialization failed: {error}"))
+ })?,
)
}
#[cfg(not(feature = "cache"))]
@@ -355,7 +352,7 @@ mod tests {
}),
pathlock: PathLockConfig {
provider: "filesystem".to_string(),
- namespace: None,
+ service_name: None,
lock_timeout_secs: 0.0,
lock_expire_secs: 30.0,
},
@@ -561,7 +558,7 @@ mod tests {
let config = RagfsConfig {
pathlock: PathLockConfig {
provider: "cache".to_string(),
- namespace: Some("builder-test".to_string()),
+ service_name: Some("builder-test".to_string()),
..PathLockConfig::default()
},
..RagfsConfig::default()
@@ -581,11 +578,11 @@ mod tests {
let Ok(endpoint) = std::env::var("REDIS_URL") else {
return;
};
- let namespace = format!("builder-pathlock-test-{}", std::process::id());
+ let service_name = format!("builder-pathlock-test-{}", std::process::id());
let config = RagfsConfig {
pathlock: PathLockConfig {
provider: "cache".to_string(),
- namespace: Some(namespace),
+ service_name: Some(service_name),
lock_expire_secs: 3.0,
..PathLockConfig::default()
},
@@ -664,7 +661,7 @@ mod tests {
let mut params = HashMap::new();
params.insert("backend".into(), ConfigValue::String("cache".into()));
params.insert(
- "cache_key_prefix".into(),
+ "service_name".into(),
ConfigValue::String(format!("builder-test-{}", uuid::Uuid::new_v4())),
);
diff --git a/crates/ragfs/src/core/mountable.rs b/crates/ragfs/src/core/mountable.rs
index 32d9c201c..530f1d07e 100644
--- a/crates/ragfs/src/core/mountable.rs
+++ b/crates/ragfs/src/core/mountable.rs
@@ -1256,7 +1256,7 @@ mod tests {
mount_path: mount_path.to_string(),
params: HashMap::new(),
backups: Some(BackendsConfig {
- namespace: "default".to_string(),
+ service_name: "mw-test".to_string(),
initial_partitions: 16,
checkpoint_interval_secs: 86_400,
provider: "filesystem".to_string(),
@@ -1768,7 +1768,7 @@ mod tests {
let mut params = HashMap::new();
params.insert("backend".into(), ConfigValue::String("cache".into()));
params.insert(
- "cache_key_prefix".into(),
+ "service_name".into(),
ConfigValue::String("mountable-shutdown-test".into()),
);
mfs.mount(PluginConfig::single_backend("queuefs", "/queue", params))
diff --git a/crates/ragfs/src/core/types.rs b/crates/ragfs/src/core/types.rs
index 9038d4abf..9056b334c 100644
--- a/crates/ragfs/src/core/types.rs
+++ b/crates/ragfs/src/core/types.rs
@@ -558,10 +558,10 @@ impl ConfigValue {
/// Multi-write backends container configuration
#[derive(Debug, Clone, Serialize, Deserialize)]
+#[serde(deny_unknown_fields)]
pub struct BackendsConfig {
- /// Cache key namespace used by cache-backed metadata.
- #[serde(default = "default_backups_namespace")]
- pub namespace: String,
+ /// OpenViking instance name used by cache-backed metadata.
+ pub service_name: String,
/// Initial number of metadata partitions.
#[serde(default = "default_initial_partitions")]
pub initial_partitions: u32,
@@ -576,11 +576,6 @@ pub struct BackendsConfig {
pub items: Vec<BackendItemConfig>,
}
-/// Return the default cache-backed metadata namespace.
-fn default_backups_namespace() -> String {
- "default".to_string()
-}
-
/// Return the default metadata partition count.
fn default_initial_partitions() -> u32 {
16
@@ -695,6 +690,7 @@ mod tests {
valid_params.insert(
"backups".to_string(),
ConfigValue::Json(serde_json::json!({
+ "service_name": "mw-prod",
"items": [{"name": "backup1", "backend": "memory"}]
})),
);
@@ -707,7 +703,8 @@ mod tests {
ConfigValue::Bool(true),
);
let config = PluginConfig::from_raw_parts("localfs", "/local", valid_params).unwrap();
- assert!(config.backups.is_some());
+ let backups = config.backups.as_ref().unwrap();
+ assert_eq!(backups.service_name, "mw-prod");
assert!(config.server_encryption_enabled);
assert!(config.primary_encryption_enabled);
assert_eq!(
@@ -722,10 +719,20 @@ mod tests {
(
HashMap::from([(
"backups".to_string(),
- ConfigValue::Json(serde_json::json!({"items": "invalid"})),
+ ConfigValue::Json(serde_json::json!({
+ "service_name": "mw-prod",
+ "items": "invalid"
+ })),
)]),
"invalid 'backups'",
),
+ (
+ HashMap::from([(
+ "backups".to_string(),
+ ConfigValue::Json(serde_json::json!({"items": []})),
+ )]),
+ "service_name",
+ ),
(
HashMap::from([(
"server_encryption_enabled".to_string(),
diff --git a/crates/ragfs/src/git/service.rs b/crates/ragfs/src/git/service.rs
index 0f1548ae6..e2b58153d 100644
--- a/crates/ragfs/src/git/service.rs
+++ b/crates/ragfs/src/git/service.rs
@@ -6650,7 +6650,7 @@ mod fast_path1_tests {
mount_path: "/local".to_string(),
params,
backups: Some(BackendsConfig {
- namespace: "default".to_string(),
+ service_name: "mw-test".to_string(),
initial_partitions: 16,
checkpoint_interval_secs: 86_400,
provider: "filesystem".to_string(),
diff --git a/crates/ragfs/src/lock/cache_provder.rs b/crates/ragfs/src/lock/cache_provder.rs
index 29274ac98..543eb4ed8 100644
--- a/crates/ragfs/src/lock/cache_provder.rs
+++ b/crates/ragfs/src/lock/cache_provder.rs
@@ -442,7 +442,7 @@ const SCRIPT_DEFINITIONS: &[ScriptDefinition] = &[
/// Redis-backed PathLock provider.
pub struct RedisPathLockProvider {
runtime: Arc<CacheRuntime>,
- namespace: String,
+ service_name: String,
hash_ttl_ms: i64,
}
@@ -450,16 +450,16 @@ impl RedisPathLockProvider {
/// Create Redis-backed PathLock storage and register its Lua scripts.
pub fn new(
runtime: Arc<CacheRuntime>,
- namespace: &str,
+ service_name: &str,
lock_expire_secs: f64,
) -> PathLockResult<Self> {
- if namespace.is_empty()
- || !namespace
+ if service_name.is_empty()
+ || !service_name
.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 '-'"
+ "pathlock Redis service_name must contain only ASCII letters, digits, '.', '_' or '-'"
.to_string(),
));
}
@@ -484,7 +484,7 @@ impl RedisPathLockProvider {
}
Ok(Self {
runtime,
- namespace: namespace.to_string(),
+ service_name: service_name.to_string(),
hash_ttl_ms: hash_ttl_ms as i64,
})
}
@@ -510,7 +510,7 @@ impl RedisPathLockProvider {
};
Ok(format!(
"ov:pathlock:{{{}}}:{suffix}:tokens",
- self.namespace
+ self.service_name
))
}
@@ -1175,12 +1175,12 @@ return redis.call("HGET", KEYS[1], ARGV[2])
})
.await
.unwrap();
- let namespace = format!("pathlock-test-{}-{test_name}", std::process::id());
- let provider = RedisPathLockProvider::new(runtime.clone(), &namespace, 1.0).unwrap();
+ let service_name = format!("pathlock-test-{}-{test_name}", std::process::id());
+ let provider = RedisPathLockProvider::new(runtime.clone(), &service_name, 1.0).unwrap();
Some((runtime, provider))
}
- /// Build two managers that share one Redis namespace.
+ /// Build two managers that share one service name.
async fn test_managers(
test_name: &str,
) -> Option<(Arc<CacheRuntime>, PathLockManager, PathLockManager, String)> {
@@ -1192,15 +1192,15 @@ return redis.call("HGET", KEYS[1], ARGV[2])
})
.await
.unwrap();
- let namespace = format!("pathlock-manager-test-{}-{test_name}", std::process::id());
+ let service_name = format!("pathlock-manager-test-{}-{test_name}", std::process::id());
let config = PathLockConfig {
provider: "cache".to_string(),
- namespace: Some(namespace.clone()),
+ service_name: Some(service_name.clone()),
lock_timeout_secs: 0.0,
lock_expire_secs: 3.0,
};
let first_provider =
- Arc::new(RedisPathLockProvider::new(runtime.clone(), &namespace, 3.0).unwrap());
+ Arc::new(RedisPathLockProvider::new(runtime.clone(), &service_name, 3.0).unwrap());
let key = first_provider
.tokens_key_for_path("/local/account-a")
.unwrap();
@@ -1211,7 +1211,7 @@ return redis.call("HGET", KEYS[1], ARGV[2])
);
let second = PathLockManager::new(
Arc::new(MemFileSystem::new()),
- Arc::new(RedisPathLockProvider::new(runtime.clone(), &namespace, 3.0).unwrap()),
+ Arc::new(RedisPathLockProvider::new(runtime.clone(), &service_name, 3.0).unwrap()),
config,
);
Some((runtime, first, second, key))
@@ -1246,8 +1246,8 @@ return redis.call("HGET", KEYS[1], ARGV[2])
})
.await
.unwrap();
- let namespace = format!("pathlock-topology-test-{}-{test_name}", std::process::id());
- let provider = RedisPathLockProvider::new(runtime.clone(), &namespace, 3.0).unwrap();
+ let service_name = format!("pathlock-topology-test-{}-{test_name}", std::process::id());
+ let provider = RedisPathLockProvider::new(runtime.clone(), &service_name, 3.0).unwrap();
provider
.try_acquire_batch_atomic(
@@ -1290,7 +1290,7 @@ return redis.call("HGET", KEYS[1], ARGV[2])
}
}
- /// Verify invalid namespace and expiry values are rejected before Redis access.
+ /// Verify invalid service_name and expiry values are rejected before Redis access.
#[test]
fn provider_rejects_invalid_configuration() {
let runtime = CacheRuntime::memory();
@@ -1325,7 +1325,7 @@ return redis.call("HGET", KEYS[1], ARGV[2])
("/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());
+ let service_name = format!("pathlock-test-{}-scope-keys", std::process::id());
for (index, (path, scope)) in cases.iter().enumerate() {
provider
.try_create_token(
@@ -1337,7 +1337,7 @@ return redis.call("HGET", KEYS[1], ARGV[2])
let raw = runtime
.execute_script(ScriptRequest {
script_id: TEST_HASH_ID.to_string(),
- keys: vec![format!("ov:pathlock:{{{namespace}}}:{scope}:tokens")],
+ keys: vec![format!("ov:pathlock:{{{service_name}}}:{scope}:tokens")],
args: vec![
RedisPathLockProvider::bytes("get"),
RedisPathLockProvider::bytes(path),
@@ -1782,7 +1782,7 @@ return redis.call("HGET", KEYS[1], ARGV[2])
provider.clone(),
PathLockConfig {
provider: "cache".to_string(),
- namespace: Some("timeout-test".to_string()),
+ service_name: Some("timeout-test".to_string()),
..PathLockConfig::default()
},
);
@@ -1806,7 +1806,7 @@ return redis.call("HGET", KEYS[1], ARGV[2])
provider.clone(),
PathLockConfig {
provider: "cache".to_string(),
- namespace: Some("race-test".to_string()),
+ service_name: Some("race-test".to_string()),
lock_expire_secs: 1.0,
..PathLockConfig::default()
},
diff --git a/crates/ragfs/src/lock/manager.rs b/crates/ragfs/src/lock/manager.rs
index cef2bdb7e..e5a64e442 100644
--- a/crates/ragfs/src/lock/manager.rs
+++ b/crates/ragfs/src/lock/manager.rs
@@ -31,7 +31,7 @@ pub struct PathLockConfig {
/// Built-in provider name: `filesystem`, `memory`, or `cache`.
pub provider: String,
/// OpenViking instance name used by the cache-backed provider.
- pub namespace: Option<String>,
+ pub service_name: Option<String>,
/// Default wait timeout for auto-acquired locks.
pub lock_timeout_secs: f64,
/// Seconds after which a lock token is considered stale.
@@ -42,7 +42,7 @@ impl Default for PathLockConfig {
fn default() -> Self {
Self {
provider: "filesystem".to_string(),
- namespace: None,
+ service_name: None,
lock_timeout_secs: 0.0,
lock_expire_secs: 30.0,
}
diff --git a/crates/ragfs/src/multibackend/factory.rs b/crates/ragfs/src/multibackend/factory.rs
index da9d8d4bc..5bf37e7f1 100644
--- a/crates/ragfs/src/multibackend/factory.rs
+++ b/crates/ragfs/src/multibackend/factory.rs
@@ -111,7 +111,7 @@ pub(crate) async fn build_inactive_multi_write_fs(
Arc::new(CacheProvider::new(
metadata_store.clone(),
runtime,
- bc.namespace.clone(),
+ bc.service_name.clone(),
)?)
}
#[cfg(not(feature = "cache"))]
diff --git a/crates/ragfs/src/plugins/queuefs/mod.rs b/crates/ragfs/src/plugins/queuefs/mod.rs
index f3da2c4b3..cf074939e 100644
--- a/crates/ragfs/src/plugins/queuefs/mod.rs
+++ b/crates/ragfs/src/plugins/queuefs/mod.rs
@@ -106,7 +106,7 @@ struct ParsedBackendConfig {
sqlite_db_path: Option<String>,
sqlite_options: SQLiteQueueOptions,
#[cfg(feature = "cache")]
- cache_key_prefix: Option<String>,
+ service_name: Option<String>,
}
/// Parsed path information
@@ -689,11 +689,9 @@ impl QueueFSPlugin {
"SQLite busy timeout in milliseconds",
),
#[cfg(feature = "cache")]
- ConfigParameter::optional(
- "cache_key_prefix",
- "string",
- "default",
- "Queue key namespace when backend=cache",
+ ConfigParameter::required_string(
+ "service_name",
+ "OpenViking service name when backend=cache",
),
],
#[cfg(feature = "cache")]
@@ -776,18 +774,22 @@ impl QueueFSPlugin {
}
};
#[cfg(feature = "cache")]
- let cache_key_prefix = match kind {
+ let service_name = match kind {
BackendKind::Cache => {
- let prefix = Self::get_string_param(config, "cache_key_prefix")
- .unwrap_or("default")
+ let service_name = Self::get_string_param(config, "service_name")
+ .ok_or_else(|| {
+ Error::config(
+ "queuefs service_name is required when backend=cache".to_string(),
+ )
+ })?
.to_string();
- if prefix.trim().is_empty() || prefix.contains(['{', '}']) {
+ if service_name.trim().is_empty() || service_name.contains(['{', '}']) {
return Err(Error::config(
- "queuefs cache_key_prefix must be non-empty and must not contain '{' or '}'"
+ "queuefs service_name must be non-empty and must not contain '{' or '}'"
.to_string(),
));
}
- Some(prefix)
+ Some(service_name)
}
_ => None,
};
@@ -800,7 +802,7 @@ impl QueueFSPlugin {
busy_timeout_ms,
},
#[cfg(feature = "cache")]
- cache_key_prefix,
+ service_name,
})
}
}
@@ -890,8 +892,8 @@ impl ServicePlugin for QueueFSPlugin {
.expect("cache runtime is validated")
.clone(),
parsed
- .cache_key_prefix
- .expect("cache key prefix is validated"),
+ .service_name
+ .expect("queuefs service_name is validated"),
)
.await?,
));
@@ -1166,7 +1168,7 @@ mod tests {
#[cfg(feature = "cache")]
assert!(config_params
.iter()
- .any(|parameter| parameter.name == "cache_key_prefix"));
+ .any(|parameter| parameter.name == "service_name"));
let config =
PluginConfig::single_backend("queuefs", "/queue", std::collections::HashMap::new());
diff --git a/docs/en/concepts/09-transaction.md b/docs/en/concepts/09-transaction.md
index 7e59fe5a0..68af79bd6 100644
--- a/docs/en/concepts/09-transaction.md
+++ b/docs/en/concepts/09-transaction.md
@@ -383,8 +383,8 @@ After startup, QueueManager resumes persisted `session_commit` jobs:
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:
+uses top-level `service_name` as the Redis 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.
@@ -408,6 +408,7 @@ Redis-backed configuration:
```json
{
+ "service_name": "production",
"cache": {
"provider": "redis",
"params": {
@@ -419,7 +420,6 @@ Redis-backed configuration:
"agfs": {
"pathlock": {
"provider": "cache",
- "namespace": "production",
"lock_expire_secs": 30.0
}
}
@@ -430,7 +430,6 @@ Redis-backed configuration:
| 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:
diff --git a/docs/en/concepts/12-metrics.md b/docs/en/concepts/12-metrics.md
index 224b96a9f..96b9b313f 100644
--- a/docs/en/concepts/12-metrics.md
+++ b/docs/en/concepts/12-metrics.md
@@ -527,7 +527,7 @@ Key fields:
- `server.observability.metrics.exporters.otel.protocol`: `"grpc"` or `"http"`
- `server.observability.metrics.exporters.otel.tls.insecure`: OTLP/gRPC only; `true` means plaintext (no TLS)
- `server.observability.metrics.exporters.otel.endpoint`: OTLP endpoint (for gRPC, use `host:4317`; for HTTP, use a full URL)
-- `server.observability.metrics.exporters.otel.service_name`: OTLP `service.name` resource attribute (default `"openviking-server"`)
+- `server.observability.metrics.exporters.otel.service_name`: OTLP `service.name` resource attribute; defaults to top-level `service_name` when omitted
- `server.observability.metrics.exporters.otel.export_interval_ms`: OTLP push interval in milliseconds (default `10000`)
- `server.observability.metrics.exporters.otel.headers`: optional custom OTLP headers; sent as gRPC metadata for gRPC and HTTP headers for HTTP
- When using gRPC, header keys in `headers` should be lowercase, for example `x-byteapm-appkey`; HTTP does not have this restriction
diff --git a/docs/en/guides/01-configuration.md b/docs/en/guides/01-configuration.md
index aa23d3cfa..d6bd29861 100644
--- a/docs/en/guides/01-configuration.md
+++ b/docs/en/guides/01-configuration.md
@@ -23,6 +23,7 @@ Create `~/.openviking/ov.conf` in your home configuration directory:
```json
{
+ "service_name": "openviking-server",
"storage": {
"workspace": "./data",
"vectordb": {
@@ -53,6 +54,10 @@ Create `~/.openviking/ov.conf` in your home configuration directory:
For `provider: "openai-codex"`, `vlm.api_key` is optional when Codex OAuth is already available.
+Top-level `service_name` defaults to `"openviking-server"`. Cache-backed modules use
+it as their Redis namespace. OTel `service_name` fields keep their own value
+when set and inherit this value when omitted.
+
### Ordered credentials in ov.conf
`vlm` and `query_planner` support an ordered `credentials` array. Embedding supports the same array inside each configured `dense`, `sparse`, or `hybrid` section. Index 0 has the highest priority; later entries provide failover credentials. The model sections remain JSON objects, and existing single-credential configurations remain supported.
@@ -1358,6 +1363,10 @@ See the [Multi-Write Storage Guide](./13-multi-write-storage.md) for more exampl
##### Global Cache Provider, CacheFS, and PathLock Configuration
+Top-level `service_name` names the OpenViking deployment. CacheFS, QueueFS with
+`backend=cache`, cache-backed PathLock, and cache-backed multi-write metadata
+derive their Redis namespaces from it.
+
The top-level `cache` section is a sibling of `storage`. Its public shape is Provider-neutral:
| Parameter | Type | Description | Default |
@@ -1370,7 +1379,6 @@ The top-level `cache` section is a sibling of `storage`. Its public shape is Pro
| Parameter | Type | Description | Default |
|-----------|------|-------------|---------|
| `backend` | str | `local` keeps the original filesystem path; `cache` enables the CacheFS wrapper | `local` |
-| `namespace` | str | CacheFS key namespace | `openviking` |
| `max_file_size_bytes` | int | Maximum full-file object size admitted to cache | `1048576` |
| `traversal_mode` | str | `backend` or `cached_traversal` | `backend` |
| `bypass_prefixes` | array[str] | Path prefixes that bypass cache | `[]` |
@@ -1380,12 +1388,12 @@ The top-level `cache` section is a sibling of `storage`. Its public shape is Pro
| Parameter | Type | Description | Default |
|-----------|------|-------------|---------|
| `provider` | str | `filesystem`, `memory`, or `cache`; `cache` uses the shared Redis CacheRuntime | `filesystem` |
-| `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
{
+ "service_name": "production",
"cache": {
"provider": "redis",
"params": {
@@ -1403,16 +1411,13 @@ The top-level `cache` section is a sibling of `storage`. Its public shape is Pro
"storage": {
"agfs": {
"cachefs": {
- "backend": "cache",
- "namespace": "production"
+ "backend": "cache"
},
"queuefs": {
- "backend": "cache",
- "cache_key_prefix": "production"
+ "backend": "cache"
},
"pathlock": {
"provider": "cache",
- "namespace": "production",
"lock_expire_secs": 30.0
}
}
@@ -1420,9 +1425,9 @@ The top-level `cache` section is a sibling of `storage`. Its public shape is Pro
}
```
-The canonical configuration has no global `cache.enabled`. CacheRuntime is initialized when CacheFS or QueueFS selects `backend=cache`, PathLock selects `provider=cache`, or multi-write selects `backups.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.
+The canonical configuration has no global `cache.enabled` and no per-module Redis namespace field. CacheRuntime is initialized when CacheFS or QueueFS selects `backend=cache`, PathLock selects `provider=cache`, or multi-write selects `backups.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"`, `storage.agfs.queuefs.redis`, and `storage.agfs.backups.provider="redis"` are rejected. Move Provider settings to top-level `cache.provider/cache.params`, select `cachefs.backend="cache"`, `queuefs.backend="cache"`, or `backups.provider="cache"`, use Redis `mode="standalone"` instead of `singleton`, and use `rediss://` instead of `tls_enabled`.
+Move Provider settings to top-level `cache.provider/cache.params`, set top-level `service_name` for shared Redis names, select `cachefs.backend="cache"`, `queuefs.backend="cache"`, or `backups.provider="cache"`, use Redis `mode="standalone"` instead of `singleton`, and use `rediss://` instead of `tls_enabled`.
##### QueueFS Configuration
@@ -1433,21 +1438,20 @@ This is a breaking configuration change. `storage.agfs.cache`, `storage.agfs.que
| `db_path` | str (optional) | SQLite database path for QueueFS when backend is `"sqlite"` or `"sqlite3"` | `null` |
| `recover_stale_sec` | int | Recover `processing` queue messages older than this many seconds on startup. `0` means recover all stale processing messages | `0` |
| `busy_timeout_ms` | int | SQLite busy timeout for QueueFS in milliseconds | `5000` |
-| `cache_key_prefix` | str | QueueFS key namespace when backend is `"cache"` | `"default"` |
Notes:
- QueueFS defaults to `sqlite` even if the main AGFS storage backend is `local`, `s3`, or `memory`.
- `mode=shared` keeps the historical global queue namespace at `/queue`; `mode=worker` isolates each worker under `/queue/worker-<index|pid>`.
- `db_path` is only used when QueueFS backend is `sqlite` or `sqlite3`.
-- `backend=cache` automatically binds the global `cache.provider + cache.params` configuration.
+- `backend=cache` automatically binds the global `cache.provider + cache.params` configuration and uses top-level `service_name` as the key prefix.
- `recover_stale_sec` and `busy_timeout_ms` apply only to SQLite backends.
- Redis Cluster endpoints are seed nodes, and `db` must be `0`. Slot routing, `MOVED`/`ASK`, topology refresh, and reconnects are handled by Fred RedisProvider.
- Redis Sentinel endpoints are Sentinel nodes and require a non-empty `master_name`; the provider handles master discovery and reconnects.
- `username` and `password` authenticate data nodes; `sentinel_username` and `sentinel_password` authenticate Sentinel nodes.
- All Redis reads go to the primary. Replica reads are not configurable.
- `tls_insecure_skip_verify=true` requires `rediss://` endpoints.
-- QueueFS cache keys use `{cache_key_prefix}:ov:*`; use different prefixes for deployments or tenants sharing one Redis cluster.
+- QueueFS cache keys use `{service_name}:ov:*`; use different service names for deployments sharing one Redis cluster.
- Redis backend runs three bounded `recover_stale` sweeps in a dedicated startup recovery thread at startup, 30 seconds, and 60 seconds to cover the heartbeat-expiry window after a container restart; it does not run long-lived periodic recovery.
- If both `storage.agfs.queuefs.db_path` and legacy `storage.agfs.queue_db_path` are set, `storage.agfs.queuefs.db_path` wins.
- If QueueFS backend is `memory`, any `db_path` or legacy `queue_db_path` is ignored.
@@ -2011,7 +2015,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` 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.
+`storage.transaction` is deprecated and kept only for legacy compatibility. Use `storage.agfs.pathlock` for the active PathLock provider and expiry configuration; Redis key names come from top-level `service_name`. 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:
diff --git a/docs/en/guides/14-ragfs-cache.md b/docs/en/guides/14-ragfs-cache.md
index 0da4bfc31..8419ece34 100644
--- a/docs/en/guides/14-ragfs-cache.md
+++ b/docs/en/guides/14-ragfs-cache.md
@@ -4,7 +4,7 @@ RAGFS cache is an optional read-cache layer for OpenViking. It speeds up full fi
CachedFileSystem assumptions:
-- Only one OpenViking / RAGFS process writes to the same namespace.
+- Only one OpenViking / RAGFS process writes to the same cache 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.
@@ -25,6 +25,7 @@ Configure the global top-level `cache` Provider, then select `backend=cache` und
```json
{
+ "service_name": "openviking-server",
"cache": {
"provider": "redis",
"params": {
@@ -42,13 +43,11 @@ Configure the global top-level `cache` Provider, then select `backend=cache` und
"backend": "local",
"cachefs": {
"backend": "cache",
- "namespace": "openviking",
"max_file_size_bytes": 1048576,
"bypass_prefixes": ["/queue", "/tmp"]
},
"pathlock": {
"provider": "cache",
- "namespace": "openviking",
"lock_expire_secs": 30.0
}
}
@@ -87,9 +86,10 @@ Available Providers:
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; use distinct namespaces for independent deployments. Distributed path locking does not remove the single-writer requirement of CachedFileSystem. Cache-backed PathLock only supports the built-in
-Redis Provider.
+OpenViking derives the PathLock Redis namespace from top-level `service_name`.
+Use distinct service names for independent deployments. Distributed path
+locking does not remove the single-writer requirement of CachedFileSystem.
+Cache-backed PathLock only supports the built-in Redis Provider.
Redis HASH keys are partitioned by logical path scope:
@@ -99,8 +99,9 @@ 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
+`{namespace}` is derived from `service_name` and used as 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.
@@ -121,9 +122,6 @@ Legacy cache configuration is no longer accepted. Migrate before upgrading:
| Redis `mode="singleton"` | `mode="standalone"` |
| `tls_enabled=true` | use `rediss://` endpoints |
| `read_from_replica` | removed; all reads use the primary |
-| Redis Provider `key_prefix` | CacheFS uses `cachefs.namespace`; QueueFS uses `queuefs.cache_key_prefix` |
-
-OpenViking rejects removed fields with a migration error instead of silently translating them.
## DynamicProvider
@@ -143,6 +141,10 @@ External Providers can be upgraded independently without rebuilding the default
## Configuration
+Top-level `service_name` defaults to `"openviking-server"` and supplies the Redis
+namespace for CacheFS, QueueFS cache backend, cache-backed PathLock, and
+cache-backed multi-write metadata.
+
The top-level `cache` section is a sibling of `storage`:
| Option | Type | Default | Description |
@@ -155,7 +157,6 @@ The top-level `cache` section is a sibling of `storage`:
| Option | Type | Default | Description |
|--------|------|---------|-------------|
| `backend` | str | `"local"` | `local` preserves existing behavior; `cache` enables CachedFileSystem |
-| `namespace` | str | `"openviking"` | Cache namespace for isolating deployments or tenants |
| `max_file_size_bytes` | int | `1048576` | Maximum full-file object size admitted to cache |
| `traversal_mode` | str | `"backend"` | Use backend traversal or `cached_traversal` for recursive APIs |
| `bypass_prefixes` | list[str] | `[]` | Path prefixes that always bypass cache |
@@ -165,7 +166,6 @@ The top-level `cache` section is a sibling of `storage`:
| Option | Type | Default | Description |
|--------|------|---------|-------------|
| `provider` | str | `"filesystem"` | `filesystem`, `memory`, or `cache` |
-| `namespace` | str or null | `null` | Required deployment namespace shared by collaborating processes when `provider=cache` |
| `lock_expire_secs` | float | `30.0` | Lock stale timeout; must be at least `1.0` |
Redis configuration:
diff --git a/docs/zh/concepts/09-transaction.md b/docs/zh/concepts/09-transaction.md
index 5fcbda7b9..44f577237 100644
--- a/docs/zh/concepts/09-transaction.md
+++ b/docs/zh/concepts/09-transaction.md
@@ -393,8 +393,8 @@ fencing token 校验通过的一方成功持有 `TreeLock(java-guide)`;失败
路径锁默认启用,并使用 `filesystem` Provider。多进程通过 Redis 协调时,
设置 `storage.agfs.pathlock.provider=cache`。Cache PathLock 要求配置顶层
-Redis Cache Provider 和非空 PathLock namespace。运行时等待超时固定为
-`0.0` 秒。`storage.transaction` 仅保留为兼容旧配置:`lock_timeout`
+Redis Cache Provider,并使用顶层 `service_name` 作为 Redis namespace。
+运行时等待超时固定为 `0.0` 秒。`storage.transaction` 仅保留为兼容旧配置:`lock_timeout`
已废弃且会被忽略,`lock_expire` 会在未显式配置新字段时自动映射,
`redo_recovery_enabled` 已废弃且会被忽略。
@@ -417,6 +417,7 @@ Redis 配置:
```json
{
+ "service_name": "production",
"cache": {
"provider": "redis",
"params": {
@@ -428,7 +429,6 @@ Redis 配置:
"agfs": {
"pathlock": {
"provider": "cache",
- "namespace": "production",
"lock_expire_secs": 30.0
}
}
@@ -439,7 +439,6 @@ Redis 配置:
| 参数 | 类型 | 说明 | 默认值 |
|------|------|------|--------|
| `provider` | str | `filesystem`、`memory` 或 `cache` | `filesystem` |
-| `namespace` | str 或 null | `provider=cache` 时必填,用于标识一个 OpenViking 部署 | `null` |
| `lock_expire_secs` | float | 未刷新的锁进入 stale 状态前的秒数 | `30.0` |
兼容旧写法:
diff --git a/docs/zh/concepts/12-metrics.md b/docs/zh/concepts/12-metrics.md
index 29c021a12..9b6d36583 100644
--- a/docs/zh/concepts/12-metrics.md
+++ b/docs/zh/concepts/12-metrics.md
@@ -525,7 +525,7 @@ max by (job) (openviking_feedback_events_total{valid="0"})
- `server.observability.metrics.exporters.otel.protocol`:`"grpc"` 或 `"http"`
- `server.observability.metrics.exporters.otel.tls.insecure`:仅对 OTLP/gRPC 生效;`true` 表示明文连接(无 TLS)
- `server.observability.metrics.exporters.otel.endpoint`:OTLP 端点(gRPC 用 `host:4317`;HTTP 必须是完整 URL)
-- `server.observability.metrics.exporters.otel.service_name`:OTLP `service.name` 资源属性(默认 `"openviking-server"`)
+- `server.observability.metrics.exporters.otel.service_name`:OTLP `service.name` 资源属性;省略时默认继承顶层 `service_name`
- `server.observability.metrics.exporters.otel.export_interval_ms`:OTLP 推送间隔,单位毫秒(默认 `10000`)
- `server.observability.metrics.exporters.otel.headers`:可选的自定义 OTLP 请求头;gRPC 会作为 metadata 发送,HTTP 会作为 headers 发送
- 使用 gRPC 时,`headers` 中的 key 需要使用小写形式,例如 `x-byteapm-appkey`;HTTP 不受该限制
diff --git a/docs/zh/guides/01-configuration.md b/docs/zh/guides/01-configuration.md
index b505ad4b1..8f06b0be9 100644
--- a/docs/zh/guides/01-configuration.md
+++ b/docs/zh/guides/01-configuration.md
@@ -23,6 +23,7 @@ openviking-server doctor
```json
{
+ "service_name": "openviking-server",
"storage": {
"workspace": "./data",
"vectordb": {
@@ -54,6 +55,9 @@ openviking-server doctor
如果 `provider` 是 `openai-codex`,并且 Codex OAuth 已经就绪,则 `vlm.api_key` 可以省略。
+顶层 `service_name` 默认是 `"openviking-server"`。使用 cache 的模块会把它作为
+Redis 命名空间。OTel 的 `service_name` 显式配置时保持原值,省略时继承该值。
+
### ov.conf 的有序凭据数组
`vlm` 和 `query_planner` 支持有序的 `credentials` 数组;Embedding 在已配置的 `dense`、`sparse` 或 `hybrid` 节内支持同样的数组。索引 0 优先级最高,后续元素提供故障切换凭据。模型配置节仍是 JSON 对象,原有单凭据配置继续兼容。
@@ -1348,6 +1352,10 @@ Python 配置层仍接受旧 sync、retry、operations、excludes 和 redirects
##### 全局 Cache Provider、CacheFS 与 PathLock 配置
+顶层 `service_name` 表示当前 OpenViking 部署名。CacheFS、`backend=cache`
+的 QueueFS、Cache PathLock 和 cache-backed 多写 metadata 都会从它生成
+Redis 命名空间。
+
全局 `cache` 与 `storage` 并列,标准配置只包含 Provider 名称和 Provider 自有参数:
| 参数 | 类型 | 说明 | 默认值 |
@@ -1360,7 +1368,6 @@ Python 配置层仍接受旧 sync、retry、operations、excludes 和 redirects
| 参数 | 类型 | 说明 | 默认值 |
|------|------|------|--------|
| `backend` | str | `local` 完全沿用原文件系统;`cache` 启用 CacheFS wrapper | `local` |
-| `namespace` | str | CacheFS key 命名空间 | `openviking` |
| `max_file_size_bytes` | int | 允许缓存的单文件最大字节数 | `1048576` |
| `traversal_mode` | str | `backend` 或 `cached_traversal` | `backend` |
| `bypass_prefixes` | array[str] | 绕过缓存的路径前缀 | `[]` |
@@ -1370,12 +1377,12 @@ Python 配置层仍接受旧 sync、retry、operations、excludes 和 redirects
| 参数 | 类型 | 说明 | 默认值 |
|------|------|------|--------|
| `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
{
+ "service_name": "production",
"cache": {
"provider": "redis",
"params": {
@@ -1393,16 +1400,13 @@ Python 配置层仍接受旧 sync、retry、operations、excludes 和 redirects
"storage": {
"agfs": {
"cachefs": {
- "backend": "cache",
- "namespace": "production"
+ "backend": "cache"
},
"queuefs": {
- "backend": "cache",
- "cache_key_prefix": "production"
+ "backend": "cache"
},
"pathlock": {
"provider": "cache",
- "namespace": "production",
"lock_expire_secs": 30.0
}
}
@@ -1410,9 +1414,9 @@ Python 配置层仍接受旧 sync、retry、operations、excludes 和 redirects
}
```
-标准配置没有全局 `cache.enabled`。当 CacheFS 或 QueueFS 选择 `backend=cache`、PathLock 选择 `provider=cache`,或多写选择 `backups.provider=cache` 时初始化 CacheRuntime。Cache PathLock 当前只支持 `cache.provider=redis`,不支持 DynamicProvider。全部模块使用本地 Provider 时不解析 `cache.params`,也不连接 Provider。
+标准配置没有全局 `cache.enabled`,也没有各模块自己的 Redis namespace 字段。当 CacheFS 或 QueueFS 选择 `backend=cache`、PathLock 选择 `provider=cache`,或多写选择 `backups.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` 和 `storage.agfs.backups.provider="redis"` 已删除并会被拒绝。请把 Provider 参数迁移到顶层 `cache.provider/cache.params`,业务模块改为 `cachefs.backend="cache"`、`queuefs.backend="cache"` 或 `backups.provider="cache"`;Redis 的 `singleton` 改为 `standalone`,`tls_enabled` 改为使用 `rediss://` endpoint。
+请把 Provider 参数迁移到顶层 `cache.provider/cache.params`,用顶层 `service_name` 生成共享 Redis 名称,业务模块改为 `cachefs.backend="cache"`、`queuefs.backend="cache"` 或 `backups.provider="cache"`;Redis 的 `singleton` 改为 `standalone`,`tls_enabled` 改为使用 `rediss://` endpoint。
##### QueueFS 配置
@@ -1423,7 +1427,6 @@ Python 配置层仍接受旧 sync、retry、operations、excludes 和 redirects
| `db_path` | str(可选) | 当 backend 为 `"sqlite"` 或 `"sqlite3"` 时使用的 QueueFS sqlite 数据库路径 | `null` |
| `recover_stale_sec` | int | 启动时恢复超过该秒数的 `processing` 队列消息;`0` 表示恢复全部 stale processing 消息 | `0` |
| `busy_timeout_ms` | int | QueueFS sqlite 的 busy timeout,单位毫秒 | `5000` |
-| `cache_key_prefix` | str | 当 backend 为 `"cache"` 时使用的 QueueFS key 命名空间 | `"default"` |
说明:
@@ -1431,11 +1434,11 @@ Python 配置层仍接受旧 sync、retry、operations、excludes 和 redirects
- `mode=shared` 会继续使用历史上的全局队列命名空间 `/queue`;`mode=worker` 会为每个 worker 隔离到 `/queue/worker-<index|pid>`。
- `db_path` 仅在 QueueFS backend 为 `sqlite` 或 `sqlite3` 时生效。
- `recover_stale_sec` 和 `busy_timeout_ms` 仅在 QueueFS backend 为 `sqlite` 或 `sqlite3` 时生效。
-- `queuefs.backend=cache` 自动绑定顶层 `cache.provider + cache.params`。
+- `queuefs.backend=cache` 自动绑定顶层 `cache.provider + cache.params`,并使用顶层 `service_name` 作为 key 前缀。
- Redis Cluster 模式的 endpoints 是初始节点,且必须配置 `db=0`;slot 路由、`MOVED`/`ASK`、拓扑更新和重连由 Fred RedisProvider 处理。
- Redis Sentinel 模式的 endpoints 是 Sentinel 节点,并且必须配置非空 `master_name`;master 发现和故障切换后的重连由 Fred RedisProvider 处理。
- `username` 和 `password` 用于 Redis 数据节点;`sentinel_username` 和 `sentinel_password` 仅用于 Sentinel 节点。
-- Cache backend 使用 `{cache_key_prefix}:ov:*` key;连接同一 Redis 集群的不同环境或租户必须配置不同的 `cache_key_prefix`。
+- Cache backend 使用 `{service_name}:ov:*` key;连接同一 Redis 集群的不同部署必须配置不同的 `service_name`。
- Cache backend 的实例心跳 TTL 为 30 秒,每 10 秒续约一次。
- Cache backend 会在独立的 startup recovery 任务中按实例心跳状态执行三次有界 `recover_stale` 扫描,时间点分别为启动后立即、30 秒和 60 秒,用于覆盖容器异常退出后旧实例心跳尚未过期的恢复窗口;正常关闭会先删除 heartbeat,使新实例可以立即恢复 processing 消息。
- 所有 Redis 读命令都发送到主节点,不提供副本读配置。
@@ -2093,7 +2096,7 @@ ov add-resource ./docs --exclude "*.tmp"
## storage.transaction 段
-`storage.transaction` 已废弃,仅保留为兼容旧配置。新配置请使用 `storage.agfs.pathlock` 配置 PathLock Provider、namespace 和过期时间。若旧字段仍然出现,OpenViking 会在运行时给出 warning;其中 `lock_timeout` 已废弃且会被忽略,`lock_expire` 会在未显式配置新字段时自动映射到新的 `pathlock` 配置,`redo_recovery_enabled` 则会被忽略。
+`storage.transaction` 已废弃,仅保留为兼容旧配置。新配置请使用 `storage.agfs.pathlock` 配置 PathLock Provider 和过期时间;Redis key 名称来自顶层 `service_name`。若旧字段仍然出现,OpenViking 会在运行时给出 warning;其中 `lock_timeout` 已废弃且会被忽略,`lock_expire` 会在未显式配置新字段时自动映射到新的 `pathlock` 配置,`redo_recovery_enabled` 则会被忽略。
推荐写法:
diff --git a/docs/zh/guides/14-ragfs-cache.md b/docs/zh/guides/14-ragfs-cache.md
index 318ffd301..174d961c0 100644
--- a/docs/zh/guides/14-ragfs-cache.md
+++ b/docs/zh/guides/14-ragfs-cache.md
@@ -4,7 +4,7 @@ RAGFS 缓存是 OpenViking 的可选读缓存层,用于加速文件全量读
CachedFileSystem 适用前提:
-- 只有一个 OpenViking / RAGFS 进程写入同一 namespace。
+- 只有一个 OpenViking / RAGFS 进程写入同一 cache namespace。
- 文件和目录变更都经过 RAGFS。
- backend 不被外部绕过 RAGFS 直接修改。
- 缓存 Provider 的同一 key 写入或删除成功后,后续读取不会返回旧值。
@@ -24,6 +24,7 @@ openviking-server doctor
```json
{
+ "service_name": "openviking-server",
"cache": {
"provider": "redis",
"params": {
@@ -41,13 +42,11 @@ openviking-server doctor
"backend": "local",
"cachefs": {
"backend": "cache",
- "namespace": "openviking",
"max_file_size_bytes": 1048576,
"bypass_prefixes": ["/queue", "/tmp"]
},
"pathlock": {
"provider": "cache",
- "namespace": "openviking",
"lock_expire_secs": 30.0
}
}
@@ -85,9 +84,9 @@ openviking-server
### Cache PathLock
将 `storage.agfs.pathlock.provider` 设为 `cache`,即可通过共享 Redis
-CacheRuntime 协调多个 OpenViking 进程的路径锁。`pathlock.namespace`
-为必填项,同一 OpenViking 部署的所有进程必须使用相同值。Cache PathLock
-只支持内置 Redis Provider。独立部署应使用不同 namespace;分布式路径锁不会解除 CachedFileSystem 的单写者前提。
+CacheRuntime 协调多个 OpenViking 进程的路径锁。OpenViking 会从顶层
+`service_name` 生成 PathLock Redis namespace。独立部署应使用不同
+`service_name`。Cache PathLock 只支持内置 Redis Provider;分布式路径锁不会解除 CachedFileSystem 的单写者前提。
Redis HASH key 按逻辑路径 scope 拆分:
@@ -97,7 +96,7 @@ ov:pathlock:{namespace}:scope:_system:tokens
ov:pathlock:{namespace}:scope:account:{account}:tokens
```
-`{namespace}` 是 Redis Cluster hash tag,因此同一部署的 PathLock key
+`{namespace}` 来自 `service_name`,也是 Redis Cluster hash tag,因此同一部署的 PathLock key
仍位于同一 slot。Tree 冲突检查只扫描请求所属 scope 的 HASH。`/` 和
`/local` 使用 global HASH,但不会扫描 account 或 `_system` HASH。
跨 scope batch 会被拒绝。
@@ -116,9 +115,6 @@ ov:pathlock:{namespace}:scope:account:{account}:tokens
| Redis `mode="singleton"` | `mode="standalone"` |
| `tls_enabled=true` | endpoint 使用 `rediss://` |
| `read_from_replica` | 已删除,所有读命令统一访问主节点 |
-| Redis Provider `key_prefix` | CacheFS 使用 `cachefs.namespace`;QueueFS 使用 `queuefs.cache_key_prefix` |
-
-OpenViking 会对已删除字段直接返回迁移错误,不再静默转换。
## DynamicProvider
@@ -138,6 +134,9 @@ Provider 发布物应注明 ABI 版本、目标 OS/CPU、最低运行时版本
## 配置项
+顶层 `service_name` 默认是 `"openviking-server"`,会为 CacheFS、QueueFS cache backend、
+Cache PathLock 和 cache-backed 多写 metadata 提供 Redis namespace。
+
顶层 `cache` 与 `storage` 并列:
| 参数 | 类型 | 默认值 | 说明 |
@@ -150,7 +149,6 @@ Provider 发布物应注明 ABI 版本、目标 OS/CPU、最低运行时版本
| 参数 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| `backend` | str | `"local"` | `local` 沿用原逻辑;`cache` 启用 CachedFileSystem |
-| `namespace` | str | `"openviking"` | 缓存命名空间,用于隔离不同部署或租户 |
| `max_file_size_bytes` | int | `1048576` | 允许进入缓存的最大完整文件大小 |
| `traversal_mode` | str | `"backend"` | 递归 API 使用 backend 遍历或 `cached_traversal` |
| `bypass_prefixes` | list[str] | `[]` | 强制绕过缓存的路径前缀 |
@@ -160,7 +158,6 @@ Provider 发布物应注明 ABI 版本、目标 OS/CPU、最低运行时版本
| 参数 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| `provider` | str | `"filesystem"` | `filesystem`、`memory` 或 `cache` |
-| `namespace` | str 或 null | `null` | `provider=cache` 时必填,同一部署的协作进程共享此命名空间 |
| `lock_expire_secs` | float | `30.0` | 锁 stale 超时;不得小于 `1.0` |
Redis 配置:
diff --git a/examples/ov.conf.example b/examples/ov.conf.example
index 8650d0b0c..594b69ee6 100644
--- a/examples/ov.conf.example
+++ b/examples/ov.conf.example
@@ -1,4 +1,5 @@
{
+ "service_name": "openviking-server",
"server": {
"host": "0.0.0.0",
"port": 1933,
@@ -90,13 +91,11 @@
},
"cachefs": {
"backend": "local",
- "namespace": "openviking",
"max_file_size_bytes": 1048576,
"bypass_prefixes": ["/queue", "/tmp"],
},
"queuefs": {
"backend": "sqlite",
- "cache_key_prefix": "default",
},
"pathlock": {
"provider": "filesystem",
diff --git a/openviking/server/config.py b/openviking/server/config.py
index 798642b4a..4f07f587a 100644
--- a/openviking/server/config.py
+++ b/openviking/server/config.py
@@ -19,7 +19,9 @@ from openviking_cli.utils.config.config_loader import (
resolve_config_path,
)
from openviking_cli.utils.config.config_utils import (
+ DEFAULT_SERVICE_NAME,
format_validation_error,
+ normalize_service_name,
warn_unknown_config_fields,
)
from openviking_cli.utils.config.consts import (
@@ -430,6 +432,36 @@ def get_server_url_from_server_data(server_data: object) -> str:
return f"http://{host}:{port}"
+def _inherit_otel_service_names(server_data: Dict[str, Any], service_name: str) -> None:
+ """Fill omitted OTel service_name fields from the top-level service name."""
+ if "observability" not in server_data:
+ server_data["observability"] = {}
+ observability = server_data["observability"]
+ if not isinstance(observability, dict):
+ return
+
+ for key in ("traces", "logs"):
+ if key not in observability:
+ observability[key] = {"service_name": service_name}
+ elif isinstance(observability[key], dict) and "service_name" not in observability[key]:
+ observability[key]["service_name"] = service_name
+
+ if "metrics" not in observability:
+ observability["metrics"] = {}
+ metrics = observability["metrics"]
+ if not isinstance(metrics, dict):
+ return
+ if "exporters" not in metrics:
+ metrics["exporters"] = {}
+ exporters = metrics["exporters"]
+ if not isinstance(exporters, dict):
+ return
+ if "otel" not in exporters:
+ exporters["otel"] = {"service_name": service_name}
+ elif isinstance(exporters["otel"], dict) and "service_name" not in exporters["otel"]:
+ exporters["otel"]["service_name"] = service_name
+
+
def load_server_config(config_path: Optional[str] = None) -> ServerConfig:
"""Load server configuration from ov.conf.
@@ -467,6 +499,9 @@ def load_server_config(config_path: Optional[str] = None) -> ServerConfig:
server_data = {}
if not isinstance(server_data, dict):
raise ValueError(f"Invalid server config in {path}: 'server' section must be an object")
+ server_data = dict(server_data)
+ service_name = normalize_service_name(data.get("service_name", DEFAULT_SERVICE_NAME))
+ _inherit_otel_service_names(server_data, service_name)
# Convert auth_mode string — built-in enums are converted to their string
# value; custom modes are kept as-is for plugin extensibility.
diff --git a/openviking/utils/agfs_utils.py b/openviking/utils/agfs_utils.py
index 6acc259e1..396e35a63 100644
--- a/openviking/utils/agfs_utils.py
+++ b/openviking/utils/agfs_utils.py
@@ -13,6 +13,10 @@ from threading import Thread
from typing import Any, Callable, Dict
from openviking_cli.utils.config.config_loader import resolve_config_path
+from openviking_cli.utils.config.config_utils import (
+ DEFAULT_SERVICE_NAME,
+ normalize_service_name,
+)
from openviking_cli.utils.config.consts import DEFAULT_OV_CONF, OPENVIKING_CONFIG_ENV
from openviking_cli.utils.logger import get_logger
@@ -28,6 +32,11 @@ class RagfsBindingConfig:
root_key: bytes | None = None
provider_type: int | None = None
log: Dict[str, Any] | None = None
+ service_name: str = DEFAULT_SERVICE_NAME
+
+ def __post_init__(self) -> None:
+ """Validate the service name used by cache-backed modules."""
+ object.__setattr__(self, "service_name", normalize_service_name(self.service_name))
def encryption_enabled(self) -> bool:
"""Return whether the binding stack should include the encryption layer."""
@@ -60,17 +69,19 @@ class RagfsBindingConfig:
cachefs,
cachefs_backend == "cache",
uses_runtime,
+ self.service_name,
)
elif self.cache is not None:
- cache_config = _disabled_cache_config(cachefs)
+ cache_config = _disabled_cache_config(cachefs, self.service_name)
else:
if uses_runtime:
raise ValueError(
"top-level cache config is required when CacheFS, QueueFS, cache-backed PathLock, "
"or cache-backed multi-write uses the shared Runtime"
)
- cache_config = _disabled_cache_config(cachefs)
+ cache_config = _disabled_cache_config(cachefs, self.service_name)
binding_config: Dict[str, Any] = {
+ "service_name": self.service_name,
"cache": cache_config,
"pathlock": pathlock,
}
@@ -91,13 +102,16 @@ class RagfsBindingConfig:
return binding_config
-def _disabled_cache_config(cachefs_model: Any) -> Dict[str, Any]:
+def _disabled_cache_config(
+ cachefs_model: Any, service_name: str = DEFAULT_SERVICE_NAME
+) -> Dict[str, Any]:
+ """Build the disabled cache config shape; service_name is carried at binding top level."""
+ normalize_service_name(service_name)
traversal_mode = getattr(cachefs_model, "traversal_mode", "backend")
return {
"enabled": False,
"runtime_enabled": False,
"provider": "redis",
- "namespace": getattr(cachefs_model, "namespace", "openviking"),
"max_file_size_bytes": getattr(cachefs_model, "max_file_size_bytes", 1024 * 1024),
"traversal_mode": getattr(traversal_mode, "value", traversal_mode),
"bypass_prefixes": list(getattr(cachefs_model, "bypass_prefixes", [])),
@@ -109,10 +123,12 @@ def _build_provider_cache_config(
cachefs_model: Any,
cachefs_enabled: bool,
runtime_enabled: bool,
+ service_name: str,
) -> Dict[str, Any]:
+ """Build a provider-backed cache config that shares the top-level service name."""
provider = provider_config.provider.strip()
params = dict(provider_config.params)
- cache_config = _disabled_cache_config(cachefs_model)
+ cache_config = _disabled_cache_config(cachefs_model, service_name)
cache_config.update(
{
"enabled": cachefs_enabled,
@@ -200,6 +216,7 @@ def build_runtime_ragfs_binding_config(config: Any) -> tuple[RagfsBindingConfig,
agfs=agfs_config,
cache=cache_config,
log=binding_log,
+ service_name=_get_config_value(config, "service_name", DEFAULT_SERVICE_NAME),
), None
root_key = _run_coro_blocking(encryptor.provider.get_root_key())
@@ -213,6 +230,7 @@ def build_runtime_ragfs_binding_config(config: Any) -> tuple[RagfsBindingConfig,
root_key=bytes(root_key),
provider_type=encryptor.provider_type,
log=binding_log,
+ service_name=_get_config_value(config, "service_name", DEFAULT_SERVICE_NAME),
),
encryptor,
)
@@ -251,7 +269,9 @@ def resolve_queuefs_mount_point(config: Any = None) -> str:
return "/queue"
-def _build_queuefs_plugin_config(agfs_config: Any, data_path: Path) -> Dict[str, Any]:
+def _build_queuefs_plugin_config(
+ agfs_config: Any, data_path: Path, service_name: str = DEFAULT_SERVICE_NAME
+) -> Dict[str, Any]:
"""Build QueueFS plugin configuration from AGFS config."""
default_queue_db_path = data_path / "_system" / "queue" / "queue.db"
queuefs_config = getattr(agfs_config, "queuefs", None)
@@ -276,15 +296,20 @@ def _build_queuefs_plugin_config(agfs_config: Any, data_path: Path) -> Dict[str,
plugin_config["db_path"] = queue_db_path
if backend == "cache":
- plugin_config["cache_key_prefix"] = queuefs_config.cache_key_prefix
+ plugin_config["service_name"] = service_name
return plugin_config
def _generate_plugin_config(
- agfs_config: Any, data_path: Path, server_encryption_enabled: bool = False
+ agfs_config: Any,
+ data_path: Path,
+ server_encryption_enabled: bool = False,
+ *,
+ service_name: str = DEFAULT_SERVICE_NAME,
) -> Dict[str, Any]:
"""Dynamically generate RAGFS plugin configuration based on backend type."""
+ service_name = normalize_service_name(service_name)
config = {
"serverinfofs": {
"enabled": True,
@@ -296,7 +321,7 @@ def _generate_plugin_config(
"queuefs": {
"enabled": True,
"path": "/queue",
- "config": _build_queuefs_plugin_config(agfs_config, data_path),
+ "config": _build_queuefs_plugin_config(agfs_config, data_path, service_name),
},
}
@@ -326,7 +351,7 @@ def _generate_plugin_config(
# Add multi-write fields if backups are configured
if backups_config is not None:
# Serialize backups config to dict for FFI JSON passthrough
- mount_config["backups"] = _serialize_backups_config(backups_config, data_path)
+ mount_config["backups"] = _serialize_backups_config(backups_config, data_path, service_name)
mount_config["server_encryption_enabled"] = server_encryption_enabled
mount_config["primary_encryption_enabled"] = server_encryption_enabled
@@ -405,7 +430,7 @@ def _serialize_s3_plugin_params(s3_config: Any) -> Dict[str, Any]:
def _dump_config_object(config: Any) -> Dict[str, Any]:
- """Dump a pydantic or namespace-like config object without None values."""
+ """Dump a pydantic or attribute-style config object without None values."""
if hasattr(config, "model_dump"):
return config.model_dump(exclude_none=True)
if isinstance(config, dict):
@@ -482,7 +507,9 @@ def _normalize_backup_item(item: Any, data_path: Path) -> Dict[str, Any]:
return item_dict
-def _serialize_backups_config(backups_config: Any, data_path: Path) -> Dict[str, Any]:
+def _serialize_backups_config(
+ backups_config: Any, data_path: Path, service_name: str = DEFAULT_SERVICE_NAME
+) -> Dict[str, Any]:
"""Serialize V2 backups while warning about and stripping legacy fields."""
result = _dump_config_object(backups_config)
deprecated_fields = []
@@ -516,6 +543,7 @@ def _serialize_backups_config(backups_config: Any, data_path: Path) -> Dict[str,
"Deprecated backups configuration fields are ignored: %s",
", ".join(dict.fromkeys(deprecated_fields)),
)
+ result["service_name"] = service_name
return result
@@ -653,7 +681,12 @@ def mount_agfs_backend(agfs: Any, config: RagfsBindingConfig | Any) -> None:
config.encryption_enabled() if isinstance(config, RagfsBindingConfig) else False
)
config = _generate_plugin_config(
- agfs_config, data_path, server_encryption_enabled=server_encryption_enabled
+ agfs_config,
+ data_path,
+ server_encryption_enabled=server_encryption_enabled,
+ service_name=config.service_name
+ if isinstance(config, RagfsBindingConfig)
+ else DEFAULT_SERVICE_NAME,
)
for plugin_name, plugin_config in config.items():
diff --git a/openviking_cli/utils/config/agfs_config.py b/openviking_cli/utils/config/agfs_config.py
index fb8de031b..d4698a0db 100644
--- a/openviking_cli/utils/config/agfs_config.py
+++ b/openviking_cli/utils/config/agfs_config.py
@@ -135,13 +135,9 @@ class QueueFSConfig(BaseModel):
description="SQLite busy timeout for QueueFS in milliseconds.",
)
- cache_key_prefix: str = Field(
- default="default",
- description="Queue key namespace when backend is 'cache'.",
- )
-
@model_validator(mode="after")
def validate_config(self):
+ """Validate QueueFS mode and backend choices."""
valid_modes = {"shared", "worker"}
if self.mode not in valid_modes:
raise ValueError("queuefs mode must be one of: 'shared', 'worker'")
@@ -156,12 +152,6 @@ class QueueFSConfig(BaseModel):
raise ValueError("queuefs recover_stale_sec must be >= 0")
if self.busy_timeout_ms < 0:
raise ValueError("queuefs busy_timeout_ms must be >= 0")
- if not self.cache_key_prefix.strip() or any(
- marker in self.cache_key_prefix for marker in ("{", "}")
- ):
- raise ValueError(
- "queuefs cache_key_prefix must be non-empty and must not contain '{' or '}'"
- )
return self
@@ -179,7 +169,6 @@ class AGFSCacheFSConfig(BaseModel):
default="local",
description="CacheFS backend: 'local' | 'cache'",
)
- namespace: str = Field(default="openviking", description="RAGFS cache namespace")
max_file_size_bytes: int = Field(
default=1024 * 1024,
description="Maximum full-file object size admitted to cache",
@@ -195,8 +184,7 @@ class AGFSCacheFSConfig(BaseModel):
@model_validator(mode="after")
def validate_config(self):
- if not self.namespace.strip():
- raise ValueError("cachefs namespace must not be empty")
+ """Validate CacheFS limits."""
if self.max_file_size_bytes <= 0:
raise ValueError("cachefs max_file_size_bytes must be > 0")
return self
@@ -312,10 +300,6 @@ class AGFSPathLockConfig(BaseModel):
default="filesystem",
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,
description="Deprecated internal field. Runtime auto-pathlock wait timeout is fixed at 0.0 seconds.",
@@ -330,18 +314,6 @@ class AGFSPathLockConfig(BaseModel):
"""Validate provider and timeout/expiry ranges."""
if self.provider not in {"filesystem", "memory", "cache"}:
raise ValueError("pathlock provider must be one of: 'filesystem', 'memory', 'cache'")
- if self.provider == "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/openviking_cli/utils/config/config_utils.py b/openviking_cli/utils/config/config_utils.py
index e2a4d2637..91f4a8c6a 100644
--- a/openviking_cli/utils/config/config_utils.py
+++ b/openviking_cli/utils/config/config_utils.py
@@ -9,6 +9,8 @@ from typing import Any, Optional, get_args, get_origin
from pydantic import BaseModel, ValidationError
+DEFAULT_SERVICE_NAME = "openviking-server"
+
def suggest_closest_field(field_name: str, valid_fields: set[str]) -> Optional[str]:
"""Return the closest matching field name when it is similar enough."""
@@ -128,6 +130,18 @@ def warn_unknown_config_fields(
)
+def normalize_service_name(value: Any, field_name: str = "service_name") -> str:
+ """Return a validated service name for cache namespaces and OTel defaults."""
+ if not isinstance(value, str):
+ raise ValueError(f"{field_name} must be a string")
+ normalized = value.strip()
+ if not normalized:
+ raise ValueError(f"{field_name} must not be empty")
+ if any(not (char.isascii() and (char.isalnum() or char in "._-")) for char in normalized):
+ raise ValueError(f"{field_name} must contain only ASCII letters, digits, '.', '_' or '-'")
+ return normalized
+
+
def format_validation_error(
*,
root_model: type[BaseModel],
diff --git a/openviking_cli/utils/config/open_viking_config.py b/openviking_cli/utils/config/open_viking_config.py
index 478a3cae4..3c2b6d0ab 100644
--- a/openviking_cli/utils/config/open_viking_config.py
+++ b/openviking_cli/utils/config/open_viking_config.py
@@ -17,7 +17,9 @@ from .agent_evolution_config import AgentEvolutionConfig
from .cache_config import CacheConfig
from .config_loader import resolve_config_path
from .config_utils import (
+ DEFAULT_SERVICE_NAME,
format_validation_error,
+ normalize_service_name,
warn_unknown_config_fields,
warn_unknown_fields,
)
@@ -196,6 +198,10 @@ class OpenVikingConfig(BaseModel):
default=None,
description="Deprecated and ignored. User is the only data-plane identity.",
)
+ service_name: str = Field(
+ default=DEFAULT_SERVICE_NAME,
+ description="OpenViking deployment name shared by cache namespaces and OTel defaults",
+ )
cache: Optional[CacheConfig] = Field(
default=None,
@@ -373,10 +379,23 @@ class OpenVikingConfig(BaseModel):
)
return self
+ @model_validator(mode="after")
+ def _validate_service_name(self) -> "OpenVikingConfig":
+ """Validate and normalize the top-level service name."""
+ self.service_name = normalize_service_name(self.service_name)
+ return self
+
@model_validator(mode="after")
def _validate_cache_runtime_config(self) -> "OpenVikingConfig":
+ """Require the shared cache Provider whenever AGFS selects a cache-backed runtime."""
agfs = self.storage.agfs
- uses_canonical_cache = agfs.cachefs.backend == "cache" or agfs.queuefs.backend == "cache"
+ backups = agfs.backups or {}
+ uses_canonical_cache = (
+ agfs.cachefs.backend == "cache"
+ or agfs.queuefs.backend == "cache"
+ or agfs.pathlock.provider == "cache"
+ or backups.get("provider", "filesystem") == "cache"
+ )
if uses_canonical_cache and self.cache is None:
raise ValueError("top-level cache config is required when an AGFS backend uses cache")
return self
diff --git a/openviking_cli/utils/config/telemetry_config.py b/openviking_cli/utils/config/telemetry_config.py
index 1411bc811..b5b53ff9c 100644
--- a/openviking_cli/utils/config/telemetry_config.py
+++ b/openviking_cli/utils/config/telemetry_config.py
@@ -2,13 +2,15 @@
# SPDX-License-Identifier: AGPL-3.0
from pydantic import BaseModel, Field
+from .config_utils import DEFAULT_SERVICE_NAME
+
class TracerConfig(BaseModel):
"""OpenTelemetry tracer configuration."""
enabled: bool = Field(default=False, description="Enable OpenTelemetry tracing")
endpoint: str = Field(default="", description="OTLP gRPC endpoint")
- service_name: str = Field(default="openviking", description="Service name for tracing")
+ service_name: str = Field(default=DEFAULT_SERVICE_NAME, description="Service name for tracing")
topic: str = Field(default="", description="Trace topic")
ak: str = Field(default="", description="Access key")
sk: str = Field(default="", description="Secret key")
diff --git a/tests/misc/test_config_validation.py b/tests/misc/test_config_validation.py
index a632835c8..409e2442e 100644
--- a/tests/misc/test_config_validation.py
+++ b/tests/misc/test_config_validation.py
@@ -191,8 +191,11 @@ def test_agfs_queuefs_validation_rejects_invalid_shapes(queuefs, match):
def test_top_level_cache_provider_params_build_redis_binding_config():
+ assert OpenVikingConfig.from_dict({}).service_name == "openviking-server"
+
config = OpenVikingConfig.from_dict(
{
+ "service_name": "tenant-a",
"cache": {
"provider": "redis",
"params": {
@@ -207,7 +210,7 @@ def test_top_level_cache_provider_params_build_redis_binding_config():
},
"storage": {
"workspace": "/tmp/ov-test",
- "agfs": {"cachefs": {"backend": "cache", "namespace": "tenant-a"}},
+ "agfs": {"cachefs": {"backend": "cache"}},
},
}
)
@@ -215,14 +218,15 @@ def test_top_level_cache_provider_params_build_redis_binding_config():
binding = RagfsBindingConfig(
agfs=config.storage.agfs,
cache=config.cache,
+ service_name=config.service_name,
).to_binding_dict()
assert config.cache.provider == "redis"
assert config.cache.params["mode"] == "sentinel"
+ assert binding["service_name"] == "tenant-a"
assert binding["cache"]["enabled"] is True
assert binding["cache"]["runtime_enabled"] is True
assert binding["cache"]["provider"] == "redis"
- assert binding["cache"]["namespace"] == "tenant-a"
assert binding["cache"]["redis"]["mode"] == "sentinel"
assert binding["cache"]["redis"]["master_name"] == "mymaster"
@@ -230,6 +234,7 @@ def test_top_level_cache_provider_params_build_redis_binding_config():
def test_queuefs_cache_uses_top_level_provider_without_enabling_cachefs():
config = OpenVikingConfig.model_validate(
{
+ "service_name": "queue-runtime",
"cache": {
"provider": "redis",
"params": {"endpoints": ["redis://redis:6379"]},
@@ -238,10 +243,7 @@ def test_queuefs_cache_uses_top_level_provider_without_enabling_cachefs():
"workspace": "/tmp/ov-test",
"agfs": {
"cachefs": {"backend": "local"},
- "queuefs": {
- "backend": "cache",
- "cache_key_prefix": "queue-runtime",
- },
+ "queuefs": {"backend": "cache"},
},
},
}
@@ -250,12 +252,20 @@ def test_queuefs_cache_uses_top_level_provider_without_enabling_cachefs():
binding = RagfsBindingConfig(
agfs=config.storage.agfs,
cache=config.cache,
+ service_name=config.service_name,
).to_binding_dict()
assert binding["cache"]["enabled"] is False
assert binding["cache"]["runtime_enabled"] is True
assert binding["cache"]["redis"]["endpoints"] == ["redis://redis:6379"]
+ plugins = _generate_plugin_config(
+ config.storage.agfs,
+ Path("/tmp/ov-test"),
+ service_name=config.service_name,
+ )
+ assert plugins["queuefs"]["config"]["service_name"] == "queue-runtime"
+
def test_top_level_cache_params_ignore_removed_replica_read_config():
config = OpenVikingConfig.model_validate(
@@ -736,7 +746,7 @@ def test_ragfs_binding_config_builds_single_binding_dict_for_local_backend(tmp_p
agfs_config = AGFSConfig(
path=str(tmp_path),
backend="local",
- cachefs={"backend": "cache", "namespace": "runtime-cache"},
+ cachefs={"backend": "cache"},
)
config = RagfsBindingConfig(
@@ -744,6 +754,7 @@ def test_ragfs_binding_config_builds_single_binding_dict_for_local_backend(tmp_p
cache=CacheConfig(provider="redis", params={}),
root_key=b"\x01" * 32,
provider_type=7,
+ service_name="runtime-cache",
)
binding = config.to_binding_dict()
@@ -754,7 +765,7 @@ def test_ragfs_binding_config_builds_single_binding_dict_for_local_backend(tmp_p
}
assert binding["cache"]["enabled"] is True
assert binding["cache"]["runtime_enabled"] is True
- assert binding["cache"]["namespace"] == "runtime-cache"
+ assert binding["service_name"] == "runtime-cache"
assert binding["pathlock"] == {
"provider": "filesystem",
"lock_expire_secs": 30.0,
@@ -766,12 +777,13 @@ def test_ragfs_binding_enables_runtime_for_queuefs_cache_backend(tmp_path):
agfs_config = AGFSConfig(
path=str(tmp_path),
backend="local",
- queuefs={"backend": "cache", "cache_key_prefix": "queue-runtime"},
+ queuefs={"backend": "cache"},
)
binding = RagfsBindingConfig(
agfs=agfs_config,
cache=CacheConfig(provider="redis", params={}),
+ service_name="queue-runtime",
).to_binding_dict()
assert binding["cache"]["enabled"] is False
@@ -789,35 +801,35 @@ def test_ragfs_binding_enables_runtime_for_multiwrite_cache_provider(tmp_path):
binding = RagfsBindingConfig(
agfs=agfs_config,
cache=CacheConfig(provider="redis", params={}),
+ service_name="mw-runtime",
).to_binding_dict()
+ assert binding["service_name"] == "mw-runtime"
assert binding["cache"]["enabled"] is False
assert binding["cache"]["runtime_enabled"] is True
+ backups = _generate_plugin_config(
+ agfs_config,
+ tmp_path,
+ service_name="mw-runtime",
+ )["localfs"]["config"]["backups"]
+ assert backups["service_name"] == "mw-runtime"
+
def test_agfs_pathlock_config_validates_provider_and_expiry(tmp_path):
- """PathLock config validates Redis namespace and expiry boundaries."""
+ """PathLock config validates provider and expiry boundaries."""
config = AGFSConfig(
path=str(tmp_path),
backend="local",
pathlock={
"provider": "cache",
- "namespace": "prod-a",
"lock_expire_secs": 60.0,
},
)
assert config.pathlock.provider == "cache"
- assert config.pathlock.namespace == "prod-a"
assert config.pathlock.lock_expire_secs == 60.0
- 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})
@@ -832,36 +844,33 @@ def test_redis_pathlock_enables_shared_runtime_without_cachefs(tmp_path):
},
"storage": {
"workspace": str(tmp_path),
- "agfs": {
- "pathlock": {
- "provider": "cache",
- "namespace": "prod-a",
- }
- },
+ "agfs": {"pathlock": {"provider": "cache"}},
},
+ "service_name": "prod-a",
}
)
binding = RagfsBindingConfig(
agfs=config.storage.agfs,
cache=config.cache,
+ service_name=config.service_name,
).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,
}
+ assert binding["service_name"] == "prod-a"
def test_create_agfs_client_uses_single_binding_config_object(monkeypatch, tmp_path):
agfs_config = AGFSConfig(
path=str(tmp_path),
backend="memory",
- cachefs={"backend": "cache", "namespace": "runtime-cache"},
+ cachefs={"backend": "cache"},
)
def _fake_get_binding_client():
@@ -872,12 +881,13 @@ def test_create_agfs_client_uses_single_binding_config_object(monkeypatch, tmp_p
config = RagfsBindingConfig(
agfs=agfs_config,
cache=CacheConfig(provider="redis", params={}),
+ service_name="runtime-cache",
)
client = create_agfs_client(config)
assert isinstance(client, _FakeBindingClient)
+ assert client.config["service_name"] == "runtime-cache"
assert client.config["cache"]["enabled"] is True
- assert client.config["cache"]["namespace"] == "runtime-cache"
assert any(call[0] == "memfs" for call in client.mount_calls)
diff --git a/tests/test_server_config_loader.py b/tests/test_server_config_loader.py
index 0414eec6a..d78ab065e 100644
--- a/tests/test_server_config_loader.py
+++ b/tests/test_server_config_loader.py
@@ -292,6 +292,7 @@ def test_load_server_config_trace_local_defaults(tmp_path):
traces = config.observability.traces
assert traces.enabled is True
assert traces.protocol == "local"
+ assert traces.service_name == "openviking-server"
assert traces.local_path == "~/.openviking/logs/traces.jsonl"
assert traces.local_rotation_mb == 40
assert traces.local_backup_count == 2