Skip to content

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

feat(pathlock): adjust pathlock config (#3854)

baojun-zhangbd5cce09c7d7
diff --git a/crates/ragfs-python/src/lib.rs b/crates/ragfs-python/src/lib.rs
index 2e44b318e..1a663291a 100644
--- a/crates/ragfs-python/src/lib.rs
+++ b/crates/ragfs-python/src/lib.rs
@@ -1327,7 +1327,7 @@ impl RAGFSBindingClient {
pl_value
.get("lock_expire_secs")
.and_then(|v| v.as_f64())
- .unwrap_or(1800.0),
+ .unwrap_or(30.0),
)?;
let lock_timeout_secs = validate_timeout_secs(
pl_value
diff --git a/crates/ragfs/src/core/builder.rs b/crates/ragfs/src/core/builder.rs
index 979e4f03e..c0ea5b04d 100644
--- a/crates/ragfs/src/core/builder.rs
+++ b/crates/ragfs/src/core/builder.rs
@@ -155,7 +155,7 @@ mod tests {
pathlock: PathLockConfig {
provider: "filesystem".to_string(),
lock_timeout_secs: 0.0,
- lock_expire_secs: 1800.0,
+ lock_expire_secs: 30.0,
},
}
}
diff --git a/crates/ragfs/src/lock/manager.rs b/crates/ragfs/src/lock/manager.rs
index ef57fef1c..275a287c2 100644
--- a/crates/ragfs/src/lock/manager.rs
+++ b/crates/ragfs/src/lock/manager.rs
@@ -39,7 +39,7 @@ impl Default for PathLockConfig {
Self {
provider: "filesystem".to_string(),
lock_timeout_secs: 0.0,
- lock_expire_secs: 1800.0,
+ lock_expire_secs: 30.0,
}
}
}
@@ -311,8 +311,17 @@ impl PathLockManager {
let mut all_ok = true;
for lp in &lock_paths {
match refresh_provider.refresh_token(lp, &owner_id, now_ns).await {
- Ok(true) => {}
- _ => all_ok = false,
+ Ok(true) => {
+ info!(lease_ref = %lease_ref, owner_id = %owner_id, lock_path = %lp, "pathlock lease automatically refreshed");
+ }
+ Ok(false) => {
+ all_ok = false;
+ info!(lease_ref = %lease_ref, owner_id = %owner_id, lock_path = %lp, "pathlock lease automatic refresh failed");
+ }
+ Err(error) => {
+ all_ok = false;
+ info!(lease_ref = %lease_ref, owner_id = %owner_id, lock_path = %lp, error = %error, "pathlock lease automatic refresh failed");
+ }
}
}
drop(refresh_guard);
@@ -1108,7 +1117,7 @@ impl PathLockManager {
}
let result = if all_ok && any_ok { "refreshed" } else if any_ok { "lost" } else { "failed" };
- debug!(lease_ref = %lease.lease.lease_ref, owner_id = %lease.lease.owner_id, lock_paths = ?lease.lease.lock_paths, result = %result, "pathlock refresh completed");
+ info!(lease_ref = %lease.lease.lease_ref, owner_id = %lease.lease.owner_id, lock_paths = ?lease.lease.lock_paths, result = %result, "pathlock refresh completed");
Ok(result.to_string())
}
diff --git a/docs/en/concepts/09-transaction.md b/docs/en/concepts/09-transaction.md
index f440b20ed..8d53f380d 100644
--- a/docs/en/concepts/09-transaction.md
+++ b/docs/en/concepts/09-transaction.md
@@ -358,7 +358,7 @@ for conflicts first:
### Lock Expiry Cleanup
-**Stale lock detection**: PathLockEngine checks the fencing token timestamp. Locks older than `lock_expire` (default 1800s / 30 minutes) are considered stale and are removed automatically during acquisition.
+**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.
**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.
@@ -371,7 +371,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 1800s / 30-minute expiry) |
+| Crash while holding lock | Lock file remains in AGFS; stale detection auto-cleans on next 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 |
@@ -387,7 +387,7 @@ 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 default wait and expiry settings. `storage.transaction` remains only as a legacy compatibility layer: `lock_timeout` and `lock_expire` are automatically mapped when the new fields are unset, while `redo_recovery_enabled` is deprecated and ignored.
+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.
Recommended configuration:
@@ -396,8 +396,7 @@ Recommended configuration:
"storage": {
"agfs": {
"pathlock": {
- "lock_timeout_secs": 5.0,
- "lock_expire_secs": 1800.0
+ "lock_expire_secs": 30.0
}
}
}
@@ -410,8 +409,7 @@ Legacy compatibility form:
{
"storage": {
"transaction": {
- "lock_timeout": 5.0,
- "lock_expire": 1800.0
+ "lock_expire": 30.0
}
}
}
@@ -419,8 +417,8 @@ Legacy compatibility form:
| Parameter | Type | Description | Default |
|-----------|------|-------------|---------|
-| `lock_timeout` | float | Deprecated. Use `storage.agfs.pathlock.lock_timeout_secs`. | `0.0` |
-| `lock_expire` | float | Deprecated. Use `storage.agfs.pathlock.lock_expire_secs`. | `1800.0` |
+| `lock_timeout` | float | Deprecated and ignored. Runtime wait timeout is fixed at `0.0`. | `0.0` |
+| `lock_expire` | float | Deprecated. Use `storage.agfs.pathlock.lock_expire_secs`. | `30.0` |
### QueueFS Persistence
diff --git a/docs/en/guides/01-configuration.md b/docs/en/guides/01-configuration.md
index 28b7cc282..e15c8c6d2 100644
--- a/docs/en/guides/01-configuration.md
+++ b/docs/en/guides/01-configuration.md
@@ -1647,7 +1647,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 active PathLock configuration. When legacy fields are still present, OpenViking logs a warning at runtime; `lock_timeout` and `lock_expire` are automatically mapped when the new fields are unset, while `redo_recovery_enabled` is ignored.
+`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.
Recommended configuration:
@@ -1656,8 +1656,7 @@ Recommended configuration:
"storage": {
"agfs": {
"pathlock": {
- "lock_timeout_secs": 5.0,
- "lock_expire_secs": 1800.0
+ "lock_expire_secs": 30.0
}
}
}
@@ -1670,8 +1669,7 @@ Legacy compatibility form (not recommended for new deployments):
{
"storage": {
"transaction": {
- "lock_timeout": 5.0,
- "lock_expire": 1800.0
+ "lock_expire": 30.0
}
}
}
@@ -1679,8 +1677,8 @@ Legacy compatibility form (not recommended for new deployments):
| Parameter | Type | Description | Default |
|-----------|------|-------------|---------|
-| `lock_timeout` | float | Deprecated. Use `storage.agfs.pathlock.lock_timeout_secs`. Automatically mapped when the new field is unset. | `0.0` |
-| `lock_expire` | float | Deprecated. Use `storage.agfs.pathlock.lock_expire_secs`. Automatically mapped when the new field is unset. | `1800.0` |
+| `lock_timeout` | float | Deprecated and ignored. Runtime wait timeout is fixed at `0.0`. | `0.0` |
+| `lock_expire` | float | Deprecated. Use `storage.agfs.pathlock.lock_expire_secs`. Automatically mapped when the new field is unset. | `30.0` |
| `redo_recovery_enabled` | bool | Deprecated and ignored. Session commit phase-2 recovery now resumes from the persistent `session_commit` queue. | `true` |
For details on the lock mechanism, see [Path Locks and Crash Recovery](../concepts/09-transaction.md).
@@ -1861,7 +1859,6 @@ For detailed encryption explanations, see [Data Encryption](../concepts/10-encry
"timeout": 10
},
"transaction": {
- "lock_timeout": 0.0,
"lock_expire": 300.0
},
"vectordb": {
diff --git a/docs/zh/concepts/09-transaction.md b/docs/zh/concepts/09-transaction.md
index 5789ad948..547044a56 100644
--- a/docs/zh/concepts/09-transaction.md
+++ b/docs/zh/concepts/09-transaction.md
@@ -366,7 +366,7 @@ fencing token 校验通过的一方成功持有 `TreeLock(java-guide)`;失败
### 锁过期清理
-**陈旧锁检测**:PathLockEngine 检查 fencing token 中的时间戳。超过 `lock_expire`(默认 1800s / 30 分钟)的锁被视为陈旧锁,在加锁过程中自动移除。
+**陈旧锁检测**:PathLockEngine 检查 fencing token 中的时间戳。超过 `lock_expire`(默认 30s)的锁被视为陈旧锁,在加锁过程中自动移除。
**进程内清理**:LockManager 每 60 秒检查活跃的 LockHandle。仍持有锁文件且失活时间超过 `lock_expire` 的 handle 会被强制释放。
@@ -379,7 +379,7 @@ fencing token 校验通过的一方成功持有 `TreeLock(java-guide)`;失败
| 场景 | 恢复方式 |
|------|---------|
| session_memory 提取中途崩溃 | 从 archive 恢复 Phase 2 并继续消费 `session_commit` 任务 |
-| 锁持有期间崩溃 | 锁文件留在 AGFS,下次获取时 stale 检测自动清理(默认 1800s / 30 分钟过期)|
+| 锁持有期间崩溃 | 锁文件留在 AGFS,下次获取时 stale 检测自动清理(默认 30s 过期)|
| enqueue 后 worker 处理前崩溃 | QueueFS SQLite 持久化,worker 重启后自动拉取 |
| 孤儿索引 | L2 按需加载时清理 |
@@ -395,7 +395,7 @@ fencing token 校验通过的一方成功持有 `TreeLock(java-guide)`;失败
## 配置
-路径锁默认启用,无需额外配置。推荐通过 `storage.agfs.pathlock` 配置默认等待时间和过期时间。`storage.transaction` 仅保留为兼容旧配置:`lock_timeout` 和 `lock_expire` 会在未显式配置新字段时自动映射,`redo_recovery_enabled` 已废弃且会被忽略。
+路径锁默认启用,无需额外配置。推荐通过 `storage.agfs.pathlock` 配置过期时间。运行时等待超时固定为 `0.0` 秒,不再接受外部配置。`storage.transaction` 仅保留为兼容旧配置:`lock_timeout` 已废弃且会被忽略,`lock_expire` 会在未显式配置新字段时自动映射,`redo_recovery_enabled` 已废弃且会被忽略。
推荐写法:
@@ -404,8 +404,7 @@ fencing token 校验通过的一方成功持有 `TreeLock(java-guide)`;失败
"storage": {
"agfs": {
"pathlock": {
- "lock_timeout_secs": 5.0,
- "lock_expire_secs": 1800.0
+ "lock_expire_secs": 30.0
}
}
}
@@ -418,8 +417,7 @@ fencing token 校验通过的一方成功持有 `TreeLock(java-guide)`;失败
{
"storage": {
"transaction": {
- "lock_timeout": 5.0,
- "lock_expire": 1800.0
+ "lock_expire": 30.0
}
}
}
@@ -427,8 +425,8 @@ fencing token 校验通过的一方成功持有 `TreeLock(java-guide)`;失败
| 参数 | 类型 | 说明 | 默认值 |
|------|------|------|--------|
-| `lock_timeout` | float | 已废弃。改用 `storage.agfs.pathlock.lock_timeout_secs`。 | `0.0` |
-| `lock_expire` | float | 已废弃。改用 `storage.agfs.pathlock.lock_expire_secs`。 | `1800.0` |
+| `lock_timeout` | float | 已废弃且忽略。运行时等待超时固定为 `0.0`。 | `0.0` |
+| `lock_expire` | float | 已废弃。改用 `storage.agfs.pathlock.lock_expire_secs`。 | `30.0` |
### QueueFS 持久化
diff --git a/docs/zh/guides/01-configuration.md b/docs/zh/guides/01-configuration.md
index b32f83c27..5746dd37c 100644
--- a/docs/zh/guides/01-configuration.md
+++ b/docs/zh/guides/01-configuration.md
@@ -1824,7 +1824,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` 配置过期时间。若旧字段仍然出现,OpenViking 会在运行时给出 warning;其中 `lock_timeout` 已废弃且会被忽略,`lock_expire` 会在未显式配置新字段时自动映射到新的 `pathlock` 配置,`redo_recovery_enabled` 则会被忽略。
推荐写法:
@@ -1833,8 +1833,7 @@ openviking add-resource ./docs --exclude "*.tmp"
"storage": {
"agfs": {
"pathlock": {
- "lock_timeout_secs": 5.0,
- "lock_expire_secs": 1800.0
+ "lock_expire_secs": 30.0
}
}
}
@@ -1847,8 +1846,7 @@ openviking add-resource ./docs --exclude "*.tmp"
{
"storage": {
"transaction": {
- "lock_timeout": 5.0,
- "lock_expire": 1800.0
+ "lock_expire": 30.0
}
}
}
@@ -1856,8 +1854,8 @@ openviking add-resource ./docs --exclude "*.tmp"
| 参数 | 类型 | 说明 | 默认值 |
|------|------|------|--------|
-| `lock_timeout` | float | 已废弃。改用 `storage.agfs.pathlock.lock_timeout_secs`。未显式配置新字段时会自动映射。 | `0.0` |
-| `lock_expire` | float | 已废弃。改用 `storage.agfs.pathlock.lock_expire_secs`。未显式配置新字段时会自动映射。 | `1800.0` |
+| `lock_timeout` | float | 已废弃且忽略。运行时等待超时固定为 `0.0`。 | `0.0` |
+| `lock_expire` | float | 已废弃。改用 `storage.agfs.pathlock.lock_expire_secs`。未显式配置新字段时会自动映射。 | `30.0` |
| `redo_recovery_enabled` | bool | 已废弃且忽略。当前版本的 `session.commit` phase-2 恢复由持久化 `session_commit` 队列负责。 | `true` |
路径锁机制的详细说明见 [路径锁与崩溃恢复](../concepts/09-transaction.md)。
@@ -1943,7 +1941,6 @@ Task 记录文件位于所属账号的系统目录:
"timeout": 10
},
"transaction": {
- "lock_timeout": 0.0,
"lock_expire": 300.0
},
"vectordb": {
diff --git a/examples/ov.conf.example b/examples/ov.conf.example
index 48e8c4c9b..3b654718e 100644
--- a/examples/ov.conf.example
+++ b/examples/ov.conf.example
@@ -67,8 +67,7 @@
"timeout": 10,
"pathlock": {
"provider": "filesystem",
- "lock_timeout_secs": 0.0,
- "lock_expire_secs": 1800.0
+ "lock_expire_secs": 30.0
},
"s3": {
"bucket": null,
diff --git a/openviking_cli/utils/config/agfs_config.py b/openviking_cli/utils/config/agfs_config.py
index 304578db2..5bb01ef92 100644
--- a/openviking_cli/utils/config/agfs_config.py
+++ b/openviking_cli/utils/config/agfs_config.py
@@ -398,16 +398,27 @@ class AGFSCacheConfig(BaseModel):
class AGFSPathLockConfig(BaseModel):
"""Configuration for the native RAGFS path lock service."""
+ @model_validator(mode="after")
+ def ignore_deprecated_lock_timeout(self):
+ """Warn and force the deprecated timeout back to the fixed runtime value."""
+ if "lock_timeout_secs" in self.model_fields_set:
+ logger.warning(
+ "AGFSPathLockConfig: 'storage.agfs.pathlock.lock_timeout_secs' is deprecated "
+ "and ignored; the runtime wait timeout is fixed at 0.0 seconds."
+ )
+ self.lock_timeout_secs = 0.0
+ return self
+
provider: str = Field(
default="filesystem",
description="PathLock provider: 'filesystem' | 'memory'",
)
lock_timeout_secs: float = Field(
default=0.0,
- description="Default wait timeout for auto-acquired path locks in seconds.",
+ description="Deprecated internal field. Runtime auto-pathlock wait timeout is fixed at 0.0 seconds.",
)
lock_expire_secs: float = Field(
- default=1800.0,
+ default=30.0,
description="Seconds before an unrefreshed lock token becomes stale.",
)
@@ -418,8 +429,6 @@ class AGFSPathLockConfig(BaseModel):
"""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_timeout_secs < 0.0:
- raise ValueError("pathlock lock_timeout_secs must be >= 0.0")
if self.lock_expire_secs < 1.0:
raise ValueError("pathlock lock_expire_secs must be >= 1.0")
return self
diff --git a/openviking_cli/utils/config/storage_config.py b/openviking_cli/utils/config/storage_config.py
index 558365f23..2c10cf20e 100644
--- a/openviking_cli/utils/config/storage_config.py
+++ b/openviking_cli/utils/config/storage_config.py
@@ -64,19 +64,10 @@ class StorageConfig(BaseModel):
@model_validator(mode="after")
def resolve_paths(self):
"""Normalize storage paths and map legacy transaction settings into native pathlock config."""
- if (
- "lock_timeout" in self.transaction.model_fields_set
- and "lock_timeout_secs" not in self.agfs.pathlock.model_fields_set
- ):
- self.agfs.pathlock.lock_timeout_secs = self.transaction.lock_timeout
- logger.warning(
- "StorageConfig: 'transaction.lock_timeout' is deprecated. "
- "Mapped to 'storage.agfs.pathlock.lock_timeout_secs'."
- )
- elif "lock_timeout" in self.transaction.model_fields_set:
+ if "lock_timeout" in self.transaction.model_fields_set:
logger.warning(
- "StorageConfig: 'transaction.lock_timeout' is deprecated and ignored because "
- "'storage.agfs.pathlock.lock_timeout_secs' is set."
+ "StorageConfig: 'transaction.lock_timeout' is deprecated and ignored. "
+ "The runtime wait timeout is fixed at 0.0 seconds."
)
if (
diff --git a/openviking_cli/utils/config/transaction_config.py b/openviking_cli/utils/config/transaction_config.py
index 97e76acd2..4184b5254 100644
--- a/openviking_cli/utils/config/transaction_config.py
+++ b/openviking_cli/utils/config/transaction_config.py
@@ -6,20 +6,19 @@ from pydantic import BaseModel, Field
class TransactionConfig(BaseModel):
"""Deprecated compatibility settings for legacy transaction fields.
- Prefer ``storage.agfs.pathlock`` for active PathLock configuration.
+ Prefer ``storage.agfs.pathlock`` only for active expiry configuration.
"""
lock_timeout: float = Field(
default=0.0,
description=(
"Deprecated compatibility field. "
- "Use storage.agfs.pathlock.lock_timeout_secs instead. "
- "When the new field is unset, this value is mapped to it."
+ "Ignored by the current implementation; runtime wait timeout is fixed at 0.0 seconds."
),
)
lock_expire: float = Field(
- default=1800.0,
+ default=30.0,
description=(
"Deprecated compatibility field. "
"Use storage.agfs.pathlock.lock_expire_secs instead. "
diff --git a/tests/misc/test_config_validation.py b/tests/misc/test_config_validation.py
index 6059d778b..d5bffa0f3 100644
--- a/tests/misc/test_config_validation.py
+++ b/tests/misc/test_config_validation.py
@@ -730,7 +730,7 @@ def test_ragfs_binding_config_builds_single_binding_dict_for_local_backend(tmp_p
"cache": agfs_config.cache.model_dump(mode="json"),
"pathlock": {
"provider": "filesystem",
- "lock_expire_secs": 1800.0,
+ "lock_expire_secs": 30.0,
"lock_timeout_secs": 0.0,
},
}
@@ -751,8 +751,6 @@ def test_agfs_pathlock_config_validates_provider_and_expiry(tmp_path):
AGFSConfig(path=str(tmp_path), pathlock={"provider": "redis"})
with pytest.raises(ValueError, match="lock_expire_secs"):
AGFSConfig(path=str(tmp_path), pathlock={"lock_expire_secs": 0.0})
- with pytest.raises(ValueError, match="lock_timeout_secs"):
- AGFSConfig(path=str(tmp_path), pathlock={"lock_timeout_secs": -1.0})
def test_create_agfs_client_uses_single_binding_config_object(monkeypatch, tmp_path):
diff --git a/tests/unit/config/test_transaction_config.py b/tests/unit/config/test_transaction_config.py
index 6ad33b71c..8cd667025 100644
--- a/tests/unit/config/test_transaction_config.py
+++ b/tests/unit/config/test_transaction_config.py
@@ -1,5 +1,5 @@
from openviking_cli.utils.config.transaction_config import TransactionConfig
-def test_lock_expire_defaults_to_thirty_minutes():
- assert TransactionConfig().lock_expire == 30 * 60
+def test_lock_expire_defaults_to_thirty_seconds():
+ assert TransactionConfig().lock_expire == 30