Skip to content

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

feat(config): add compatible default timeout for ragfs pathlock (#3641)

baojun-zhang7c956f23bc07
diff --git a/crates/ragfs-python/src/lib.rs b/crates/ragfs-python/src/lib.rs
index 96ba44dc5..c5e4f4273 100644
--- a/crates/ragfs-python/src/lib.rs
+++ b/crates/ragfs-python/src/lib.rs
@@ -1167,10 +1167,18 @@ impl RAGFSBindingClient {
pl_value
.get("lock_expire_secs")
.and_then(|v| v.as_f64())
- .unwrap_or(300.0),
+ .unwrap_or(1800.0),
)?;
+ let lock_timeout_secs = validate_timeout_secs(
+ pl_value
+ .get("lock_timeout_secs")
+ .and_then(|v| v.as_f64())
+ .unwrap_or(0.0),
+ )?
+ .as_secs_f64();
ragfs_cfg.pathlock = PathLockConfig {
provider: provider.to_string(),
+ lock_timeout_secs,
lock_expire_secs,
};
}
diff --git a/crates/ragfs/src/core/builder.rs b/crates/ragfs/src/core/builder.rs
index da89b1cdc..979e4f03e 100644
--- a/crates/ragfs/src/core/builder.rs
+++ b/crates/ragfs/src/core/builder.rs
@@ -154,7 +154,8 @@ mod tests {
}),
pathlock: PathLockConfig {
provider: "filesystem".to_string(),
- lock_expire_secs: 300.0,
+ lock_timeout_secs: 0.0,
+ lock_expire_secs: 1800.0,
},
}
}
diff --git a/crates/ragfs/src/lock/manager.rs b/crates/ragfs/src/lock/manager.rs
index ad39d43e9..10707cd00 100644
--- a/crates/ragfs/src/lock/manager.rs
+++ b/crates/ragfs/src/lock/manager.rs
@@ -28,6 +28,8 @@ use super::types::{
pub struct PathLockConfig {
/// Built-in provider name: `filesystem` or `memory`.
pub provider: String,
+ /// Default wait timeout for auto-acquired locks.
+ pub lock_timeout_secs: f64,
/// Seconds after which a lock token is considered stale.
pub lock_expire_secs: f64,
}
@@ -36,7 +38,8 @@ impl Default for PathLockConfig {
fn default() -> Self {
Self {
provider: "filesystem".to_string(),
- lock_expire_secs: 300.0,
+ lock_timeout_secs: 0.0,
+ lock_expire_secs: 1800.0,
}
}
}
@@ -267,6 +270,11 @@ pub struct PathLockManager {
}
impl PathLockManager {
+ /// Return the configured default timeout for automatic lock acquisition.
+ pub fn default_lock_timeout(&self) -> Duration {
+ Duration::from_secs_f64(self.config.lock_timeout_secs)
+ }
+
/// Create a new PathLockManager.
pub fn new(
fs: Arc<dyn FileSystem>,
diff --git a/crates/ragfs/src/lock/wrapper.rs b/crates/ragfs/src/lock/wrapper.rs
index 4e690884b..0258203b0 100644
--- a/crates/ragfs/src/lock/wrapper.rs
+++ b/crates/ragfs/src/lock/wrapper.rs
@@ -8,8 +8,6 @@
//! `PathLockManager`.
use std::sync::Arc;
-use std::time::Duration;
-
use async_trait::async_trait;
use crate::core::filesystem::FileSystem;
@@ -20,9 +18,6 @@ use crate::core::MountableFS;
use super::manager::{AutoPathLockAction, PathLockManager};
use super::types::{PathLockKind, PathLockRequest};
-/// Default timeout for auto-acquired locks.
-const AUTO_LOCK_TIMEOUT: Duration = Duration::ZERO;
-
/// A `FileSystem` wrapper that auto-acquires path locks for mutating operations.
pub struct PathLockWrappedFS {
/// The lock manager (single source of truth).
@@ -109,7 +104,7 @@ impl FileSystem for PathLockWrappedFS {
}
let lease = self
.manager
- .acquire_exact(path, AUTO_LOCK_TIMEOUT, None)
+ .acquire_exact(path, self.manager.default_lock_timeout(), None)
.await
.map_err(|e| crate::core::Error::internal(format!("lock error: {e}")))?;
let result = self.inner.create(path).await;
@@ -134,7 +129,7 @@ impl FileSystem for PathLockWrappedFS {
}
let lease = self
.manager
- .acquire_exact(path, AUTO_LOCK_TIMEOUT, None)
+ .acquire_exact(path, self.manager.default_lock_timeout(), None)
.await
.map_err(|e| crate::core::Error::internal(format!("lock error: {e}")))?;
let result = self.inner.remove(path).await;
@@ -155,7 +150,7 @@ impl FileSystem for PathLockWrappedFS {
}
let lease = self
.manager
- .acquire_tree(path, AUTO_LOCK_TIMEOUT, None)
+ .acquire_tree(path, self.manager.default_lock_timeout(), None)
.await
.map_err(|e| crate::core::Error::internal(format!("lock error: {e}")))?;
let result = self.inner.remove_all(path).await;
@@ -186,7 +181,7 @@ impl FileSystem for PathLockWrappedFS {
}
let lease = self
.manager
- .acquire_exact(path, AUTO_LOCK_TIMEOUT, None)
+ .acquire_exact(path, self.manager.default_lock_timeout(), None)
.await
.map_err(|e| crate::core::Error::internal(format!("lock error: {e}")))?;
let result = self.inner.write(path, data, offset, flags).await;
@@ -245,7 +240,7 @@ impl FileSystem for PathLockWrappedFS {
let lease = self
.manager
- .acquire_batch(&requests, AUTO_LOCK_TIMEOUT, None)
+ .acquire_batch(&requests, self.manager.default_lock_timeout(), None)
.await
.map_err(|e| crate::core::Error::internal(format!("lock error: {e}")))?;
let result = self.inner.rename(old_path, new_path).await;
@@ -273,7 +268,7 @@ impl FileSystem for PathLockWrappedFS {
}
let lease = self
.manager
- .acquire_batch(&requests, AUTO_LOCK_TIMEOUT, None)
+ .acquire_batch(&requests, self.manager.default_lock_timeout(), None)
.await
.map_err(|e| crate::core::Error::internal(format!("lock error: {e}")))?;
let result = self.inner.replace(src_path, dst_path).await;
@@ -298,7 +293,7 @@ impl FileSystem for PathLockWrappedFS {
}
let lease = self
.manager
- .acquire_exact(path, AUTO_LOCK_TIMEOUT, None)
+ .acquire_exact(path, self.manager.default_lock_timeout(), None)
.await
.map_err(|e| crate::core::Error::internal(format!("lock error: {e}")))?;
let result = self.inner.truncate(path, size).await;
diff --git a/docs/en/concepts/09-transaction.md b/docs/en/concepts/09-transaction.md
index 613950c2c..f440b20ed 100644
--- a/docs/en/concepts/09-transaction.md
+++ b/docs/en/concepts/09-transaction.md
@@ -1,6 +1,6 @@
# Path Locks and Crash Recovery
-OpenViking uses two simple primitives — **path locks** and **redo log** — to protect the consistency of core write operations (`rm`, `mv`, `add_resource`, `session.commit`), ensuring that VikingFS, VectorDB, and QueueManager remain consistent even when failures occur.
+OpenViking uses two simple primitives — **path locks** and **persistent queue recovery** — to protect the consistency of core write operations (`rm`, `mv`, `add_resource`, `session.commit`), ensuring that VikingFS, VectorDB, and QueueManager remain consistent even when failures occur.
## Design Philosophy
@@ -13,7 +13,7 @@ OpenViking is a context database where FS is the source of truth and VectorDB is
1. **Write-exclusive**: Path locks ensure only one write operation can operate on a path at a time
2. **On by default**: All data operations automatically acquire locks; no extra configuration needed
3. **Lock as protection**: LockContext acquires locks on entry, releases on exit — no undo/journal/commit semantics
-4. **Only session_memory needs crash recovery**: RedoLog re-executes memory extraction after a process crash
+4. **Only session_memory needs crash recovery**: a persistent `session_commit` queue resumes Phase 2 after a process crash
5. **Queue operations run outside locks**: SemanticQueue/EmbeddingQueue enqueue operations are idempotent and retriable
## Architecture
@@ -57,26 +57,23 @@ class LockHandle:
**LockManager** is a global singleton managing lock lifecycle:
- Creates/releases LockHandles
- Background cleanup of leaked locks (in-process safety net)
-- Executes RedoLog recovery on startup
+- Relies on QueueManager to resume persisted `session_commit` Phase 2 work after startup
**LockContext** is an async context manager encapsulating the lock/unlock lifecycle:
```python
-from openviking.storage.transaction import LockContext, get_lock_manager
-
-async with LockContext(get_lock_manager(), [path], lock_mode="exact") as handle:
+# Conceptual example: production path locks are acquired inside the Rust ragfs layer.
+async with LockContext(lock_manager, [path], lock_mode="exact") as handle:
# Perform operations under lock protection
...
# Lock automatically released on exit (including exceptions)
```
-### Component 2: RedoLog (Crash Recovery)
-
-Used only for the memory extraction phase of `session.commit`. Writes a marker before the operation, deletes it after success, and scans for leftover markers on startup to redo.
+### Component 2: Persistent `session_commit` Queue (Crash Recovery)
-```
-/local/_system/redo/{task_id}/redo.json
-```
+`session.commit` Phase 2 no longer uses a standalone redo log. Phase 1 persists archive metadata first,
+then enqueues a durable `SessionCommitMsg`; after restart, QueueManager resumes any leftover
+`session_commit` jobs and continues Phase 2.
Memory extraction is idempotent — re-extracting from the same archive produces the same result.
@@ -207,7 +204,7 @@ hold separate ExactPathLocks for the two source files. Refreshing `preferences/.
| Problem | Solution |
|---------|----------|
-| Messages cleared but archive not written -> conversation data lost | Phase 1 without lock (incomplete archive has no side effects) + Phase 2 with RedoLog |
+| Messages cleared but archive not written -> conversation data lost | Phase 1 without lock (incomplete archive has no side effects) + Phase 2 with a persistent `session_commit` queue |
LLM calls have unpredictable latency (5s~60s+) and cannot be inside a lock-holding operation. The design splits into two phases:
@@ -218,32 +215,29 @@ Phase 1 — Archive (no lock):
3. Clear messages.jsonl
4. Clear in-memory message list
-Phase 2 — Memory extraction + write (RedoLog):
- 1. Write redo marker (archive_uri, session_uri, user identity)
+Phase 2 — Memory extraction + write (persistent `session_commit` queue):
+ 1. Persist archive metadata and enqueue `SessionCommitMsg`
2. Extract memories from archived messages (LLM)
3. Write current message state
4. Write relations
5. Directly enqueue SemanticQueue
- 6. Delete redo marker
```
**Crash recovery analysis**:
| Failure moment | State | Recovery action |
|------------|-------|----------------|
-| During Phase 1 archive write | No marker | Incomplete archive; next commit scans history/ for index, unaffected |
-| Phase 1 archive complete but messages not cleared | No marker | Archive complete + messages still present = redundant but safe |
-| During Phase 2 memory extraction/write | Redo marker exists | On startup: redo extraction + write + enqueue from archive |
-| Phase 2 complete | Redo marker deleted | No recovery needed |
+| During Phase 1 archive write | Queue not published yet | Incomplete archive; next commit scans history/ for index, unaffected |
+| Phase 1 archive complete but messages not cleared | Queue not published yet | Archive complete + messages still present = redundant but safe |
+| During Phase 2 memory extraction/write | `session_commit` job still persisted | After restart: resume the job and recover Phase 2 from archive |
+| Phase 2 complete | Archive marked complete | No recovery needed |
## LockContext
`LockContext` is an **async** context manager that encapsulates lock acquisition and release:
```python
-from openviking.storage.transaction import LockContext, get_lock_manager
-
-lock_manager = get_lock_manager()
+# Conceptual example: production path locks are acquired inside the Rust ragfs layer.
# Exact lock (write operations, semantic processing)
async with LockContext(lock_manager, [path], lock_mode="exact"):
@@ -372,11 +366,11 @@ for conflicts first:
## Crash Recovery
-`LockManager.start()` automatically scans for leftover markers in `/local/_system/redo/` on startup:
+After startup, QueueManager resumes persisted `session_commit` jobs:
| Scenario | Recovery action |
|----------|----------------|
-| session_memory extraction crash | Redo memory extraction + write + enqueue from archive |
+| 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 after enqueue, before worker processes | QueueFS SQLite persistence; worker auto-pulls after restart |
| Orphan index | Cleaned on L2 on-demand load |
@@ -387,13 +381,30 @@ for conflicts first:
|-----------------|--------|-----------------|
| Crash during operation | Lock auto-expires + stale detection | Next acquisition of same path lock |
| Crash during add_resource semantic processing | Lifecycle lock expires + SemanticProcessor re-acquires on restart | Worker restart |
-| Crash during session.commit Phase 2 | RedoLog marker + redo | On restart |
+| Crash during session.commit Phase 2 | Persistent `session_commit` queue + resumed consumption | On restart |
| Crash after enqueue, before worker | QueueFS SQLite persistence | Worker restart |
| Orphan index | L2 on-demand load cleanup | When user accesses |
## Configuration
-Path locks are enabled by default with no extra configuration needed. **The default behavior is no-wait**: if the path is locked, `LockAcquisitionError` is raised immediately. To allow wait/retry, configure the `storage.transaction` section:
+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.
+
+Recommended configuration:
+
+```json
+{
+ "storage": {
+ "agfs": {
+ "pathlock": {
+ "lock_timeout_secs": 5.0,
+ "lock_expire_secs": 1800.0
+ }
+ }
+ }
+}
+```
+
+Legacy compatibility form:
```json
{
@@ -408,8 +419,8 @@ Path locks are enabled by default with no extra configuration needed. **The defa
| Parameter | Type | Description | Default |
|-----------|------|-------------|---------|
-| `lock_timeout` | float | Lock acquisition timeout (seconds). `0` = fail immediately if locked (default). `> 0` = wait/retry up to this many seconds. | `0.0` |
-| `lock_expire` | float | Lock inactivity threshold (seconds). Locks not refreshed within this window are treated as stale and reclaimed. | `1800.0` |
+| `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` |
### QueueFS Persistence
diff --git a/docs/en/guides/01-configuration.md b/docs/en/guides/01-configuration.md
index 088415dc2..97fb549ea 100644
--- a/docs/en/guides/01-configuration.md
+++ b/docs/en/guides/01-configuration.md
@@ -1552,14 +1552,31 @@ For startup and deployment details see [Deployment](./03-deployment.md), for aut
## storage.transaction Section
-Path locks are enabled by default and usually require no configuration. **The default behavior is no-wait**: if the target path is already locked by another operation, the operation fails immediately with `LockAcquisitionError`. Set `lock_timeout` to a positive value to allow polling/retry.
+`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.
+
+Recommended configuration:
+
+```json
+{
+ "storage": {
+ "agfs": {
+ "pathlock": {
+ "lock_timeout_secs": 5.0,
+ "lock_expire_secs": 1800.0
+ }
+ }
+ }
+}
+```
+
+Legacy compatibility form (not recommended for new deployments):
```json
{
"storage": {
"transaction": {
"lock_timeout": 5.0,
- "lock_expire": 300.0
+ "lock_expire": 1800.0
}
}
}
@@ -1567,8 +1584,9 @@ Path locks are enabled by default and usually require no configuration. **The de
| Parameter | Type | Description | Default |
|-----------|------|-------------|---------|
-| `lock_timeout` | float | Path lock acquisition timeout (seconds). `0` = fail immediately if locked (default). `> 0` = wait/retry up to this many seconds, then raise `LockAcquisitionError`. | `0.0` |
-| `lock_expire` | float | Lock inactivity threshold (seconds). Locks not refreshed within this window are treated as stale and reclaimed. | `300.0` |
+| `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` |
+| `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).
diff --git a/docs/zh/concepts/09-transaction.md b/docs/zh/concepts/09-transaction.md
index 033aacf9d..5789ad948 100644
--- a/docs/zh/concepts/09-transaction.md
+++ b/docs/zh/concepts/09-transaction.md
@@ -1,6 +1,6 @@
# 路径锁与崩溃恢复
-OpenViking 通过**路径锁**和**Redo Log** 两个简单原语保护核心写操作(`rm`、`mv`、`add_resource`、`session.commit`)的一致性,确保 VikingFS、VectorDB、QueueManager 三个子系统在故障时不会出现数据不一致。
+OpenViking 通过**路径锁**和**持久化队列恢复**两个简单原语保护核心写操作(`rm`、`mv`、`add_resource`、`session.commit`)的一致性,确保 VikingFS、VectorDB、QueueManager 三个子系统在故障时不会出现数据不一致。
## 设计哲学
@@ -13,7 +13,7 @@ OpenViking 是上下文数据库,FS 是源数据,VectorDB 是派生索引。
1. **写互斥**:通过路径锁保证同一路径同一时间只有一个写操作
2. **默认生效**:所有数据操作命令自动加锁,用户无需额外配置
3. **锁即保护**:进入 LockContext 时加锁,退出时释放,没有 undo/journal/commit 语义
-4. **仅 session_memory 需要崩溃恢复**:通过 RedoLog 在进程崩溃后重做记忆提取
+4. **仅 session_memory 需要崩溃恢复**:通过持久化 `session_commit` 队列在进程崩溃后恢复 Phase 2
5. **Queue 操作在锁外执行**:SemanticQueue/EmbeddingQueue 的 enqueue 是幂等的,失败可重试
## 架构
@@ -56,28 +56,25 @@ class LockHandle:
**LockManager** 是全局单例,管理锁生命周期:
- 创建/释放 LockHandle
- 后台清理泄漏的锁(进程内安全网)
-- 启动时执行 RedoLog 恢复
+- 启动后由 QueueManager 恢复持久化的 `session_commit` Phase 2 任务
**LockContext** 是异步上下文管理器,封装加锁/解锁生命周期:
```python
-from openviking.storage.transaction import LockContext, get_lock_manager
-
-async with LockContext(get_lock_manager(), [path], lock_mode="exact") as handle:
+# Conceptual example: production path locks are acquired inside the Rust ragfs layer.
+async with LockContext(lock_manager, [path], lock_mode="exact") as handle:
# 在锁保护下执行操作
...
# 退出时自动释放锁(包括异常情况)
```
-### 组件 2:RedoLog(崩溃恢复)
-
-仅用于 `session.commit` 的记忆提取阶段。操作前写标记,成功后删标记,启动时扫描遗留标记并重做。
+### 组件 2:持久化 `session_commit` 队列(崩溃恢复)
-```
-/local/_system/redo/{task_id}/redo.json
-```
+`session.commit` 的 Phase 2 不再使用独立 RedoLog。Phase 1 会先把 archive 元数据持久化,再把
+`SessionCommitMsg` 写入持久化队列;进程重启后,QueueManager 会继续消费遗留的 `session_commit`
+任务并恢复 Phase 2。
-Memory 提取是幂等的 — 从同一个 archive 重新提取会得到相同结果。
+Memory 提取是幂等的,从同一个 archive 重新提取会得到相同结果。
## 一致性问题与解决方案
@@ -201,7 +198,7 @@ viking://user/default/memories/preferences/editor.md
| 问题 | 方案 |
|------|------|
-| 消息已清空但 archive 未写入 -> 对话数据丢失 | Phase 1 无锁(archive 不完整无副作用)+ Phase 2 RedoLog |
+| 消息已清空但 archive 未写入 -> 对话数据丢失 | Phase 1 无锁(archive 不完整无副作用)+ Phase 2 持久化 `session_commit` 队列 |
LLM 调用耗时不可控(5s~60s+),不能放在持锁操作内。设计拆为两个阶段:
@@ -212,32 +209,29 @@ Phase 1 — 归档(无锁):
3. 清空 messages.jsonl
4. 清空内存中的消息列表
-Phase 2 — 记忆提取 + 写入(RedoLog):
- 1. 写 redo 标记(archive_uri、session_uri、用户身份信息)
+Phase 2 — 记忆提取 + 写入(持久化 `session_commit` 队列):
+ 1. 持久化 archive 元数据并 enqueue `SessionCommitMsg`
2. 从归档消息提取 memories(LLM)
3. 写当前消息状态
4. 写 relations
5. 直接 enqueue SemanticQueue
- 6. 删除 redo 标记
```
**崩溃恢复分析**:
| 崩溃时间点 | 状态 | 恢复动作 |
|-----------|------|---------|
-| Phase 1 写 archive 中途 | 无标记 | archive 不完整,下次 commit 从 history/ 扫描 index,不受影响 |
-| Phase 1 archive 完成但 messages 未清空 | 无标记 | archive 完整 + messages 仍在 = 数据冗余但安全 |
-| Phase 2 记忆提取/写入中途 | redo 标记存在 | 启动恢复:从 archive 重做提取+写入+入队 |
-| Phase 2 完成 | redo 标记已删 | 无需恢复 |
+| Phase 1 写 archive 中途 | 队列未发布 | archive 不完整,下次 commit 从 history/ 扫描 index,不受影响 |
+| Phase 1 archive 完成但 messages 未清空 | 队列未发布 | archive 完整 + messages 仍在 = 数据冗余但安全 |
+| Phase 2 记忆提取/写入中途 | `session_commit` 任务仍在持久化队列中 | 重启后继续消费该任务,从 archive 恢复 Phase 2 |
+| Phase 2 完成 | archive 标记为完成 | 无需恢复 |
## LockContext
`LockContext` 是**异步**上下文管理器,封装锁的获取和释放:
```python
-from openviking.storage.transaction import LockContext, get_lock_manager
-
-lock_manager = get_lock_manager()
+# Conceptual example: production path locks are acquired inside the Rust ragfs layer.
# Exact 锁(写操作、语义处理)
async with LockContext(lock_manager, [path], lock_mode="exact"):
@@ -380,11 +374,11 @@ fencing token 校验通过的一方成功持有 `TreeLock(java-guide)`;失败
## 崩溃恢复
-`LockManager.start()` 启动时自动扫描 `/local/_system/redo/` 目录中的遗留标记:
+服务启动后,QueueManager 会继续消费持久化的 `session_commit` 任务:
| 场景 | 恢复方式 |
|------|---------|
-| session_memory 提取中途崩溃 | 从 archive 重做记忆提取 + 写入 + enqueue |
+| session_memory 提取中途崩溃 | 从 archive 恢复 Phase 2 并继续消费 `session_commit` 任务 |
| 锁持有期间崩溃 | 锁文件留在 AGFS,下次获取时 stale 检测自动清理(默认 1800s / 30 分钟过期)|
| enqueue 后 worker 处理前崩溃 | QueueFS SQLite 持久化,worker 重启后自动拉取 |
| 孤儿索引 | L2 按需加载时清理 |
@@ -395,13 +389,30 @@ fencing token 校验通过的一方成功持有 `TreeLock(java-guide)`;失败
|---------|------|---------|
| 操作中途崩溃 | 锁自动过期 + stale 检测 | 下次获取同路径锁时 |
| add_resource 语义处理中途崩溃 | 生命周期锁过期 + SemanticProcessor 重启时重新获取 | worker 重启后 |
-| session.commit Phase 2 崩溃 | RedoLog 标记 + 重做 | 重启时 |
+| session.commit Phase 2 崩溃 | 持久化 `session_commit` 队列 + 重试消费 | 重启时 |
| enqueue 后 worker 处理前崩溃 | QueueFS SQLite 持久化 | worker 重启后 |
| 孤儿索引 | L2 按需加载时清理 | 用户访问时 |
## 配置
-路径锁默认启用,无需额外配置。**默认不等待**:若路径被锁定则立即抛出 `LockAcquisitionError`。如需允许等待重试,可通过 `storage.transaction` 段配置:
+路径锁默认启用,无需额外配置。推荐通过 `storage.agfs.pathlock` 配置默认等待时间和过期时间。`storage.transaction` 仅保留为兼容旧配置:`lock_timeout` 和 `lock_expire` 会在未显式配置新字段时自动映射,`redo_recovery_enabled` 已废弃且会被忽略。
+
+推荐写法:
+
+```json
+{
+ "storage": {
+ "agfs": {
+ "pathlock": {
+ "lock_timeout_secs": 5.0,
+ "lock_expire_secs": 1800.0
+ }
+ }
+ }
+}
+```
+
+兼容旧写法:
```json
{
@@ -416,8 +427,8 @@ fencing token 校验通过的一方成功持有 `TreeLock(java-guide)`;失败
| 参数 | 类型 | 说明 | 默认值 |
|------|------|------|--------|
-| `lock_timeout` | float | 获取锁的等待超时(秒)。`0` = 立即失败(默认);`> 0` = 最多等待此时间 | `0.0` |
-| `lock_expire` | float | 锁失活阈值(秒),超过此时间未被 refresh 的锁会被视为陈旧锁并回收 | `1800.0` |
+| `lock_timeout` | float | 已废弃。改用 `storage.agfs.pathlock.lock_timeout_secs`。 | `0.0` |
+| `lock_expire` | float | 已废弃。改用 `storage.agfs.pathlock.lock_expire_secs`。 | `1800.0` |
### QueueFS 持久化
diff --git a/docs/zh/guides/01-configuration.md b/docs/zh/guides/01-configuration.md
index 3015d3e7a..2a0aaab93 100644
--- a/docs/zh/guides/01-configuration.md
+++ b/docs/zh/guides/01-configuration.md
@@ -1611,14 +1611,31 @@ openviking add-resource ./docs --exclude "*.tmp"
## storage.transaction 段
-路径锁默认启用,通常无需配置。**默认行为是不等待**:若目标路径已被其他操作锁定,操作立即失败并抛出 `LockAcquisitionError`。若需要等待重试,请将 `lock_timeout` 设为正数。
+`storage.transaction` 已废弃,仅保留为兼容旧配置。新配置请使用 `storage.agfs.pathlock`。若旧字段仍然出现,OpenViking 会在运行时给出 warning;其中 `lock_timeout` 和 `lock_expire` 会在未显式配置新字段时自动映射到新的 `pathlock` 配置,`redo_recovery_enabled` 则会被忽略。
+
+推荐写法:
+
+```json
+{
+ "storage": {
+ "agfs": {
+ "pathlock": {
+ "lock_timeout_secs": 5.0,
+ "lock_expire_secs": 1800.0
+ }
+ }
+ }
+}
+```
+
+兼容旧写法(不推荐新项目继续使用):
```json
{
"storage": {
"transaction": {
"lock_timeout": 5.0,
- "lock_expire": 300.0
+ "lock_expire": 1800.0
}
}
}
@@ -1626,8 +1643,9 @@ openviking add-resource ./docs --exclude "*.tmp"
| 参数 | 类型 | 说明 | 默认值 |
|------|------|------|--------|
-| `lock_timeout` | float | 获取路径锁的等待超时(秒)。`0` = 立即失败(默认);`> 0` = 最多等待此时间后抛出 `LockAcquisitionError` | `0.0` |
-| `lock_expire` | float | 锁失活阈值(秒)。超过此时间未被 refresh 的锁会被视为陈旧锁并回收 | `300.0` |
+| `lock_timeout` | float | 已废弃。改用 `storage.agfs.pathlock.lock_timeout_secs`。未显式配置新字段时会自动映射。 | `0.0` |
+| `lock_expire` | float | 已废弃。改用 `storage.agfs.pathlock.lock_expire_secs`。未显式配置新字段时会自动映射。 | `1800.0` |
+| `redo_recovery_enabled` | bool | 已废弃且忽略。当前版本的 `session.commit` phase-2 恢复由持久化 `session_commit` 队列负责。 | `true` |
路径锁机制的详细说明见 [路径锁与崩溃恢复](../concepts/09-transaction.md)。
diff --git a/examples/ov.conf.example b/examples/ov.conf.example
index 4527f69ad..0c3f6bb53 100644
--- a/examples/ov.conf.example
+++ b/examples/ov.conf.example
@@ -64,6 +64,11 @@
"agfs": {
"backend": "local",
"timeout": 10,
+ "pathlock": {
+ "provider": "filesystem",
+ "lock_timeout_secs": 0.0,
+ "lock_expire_secs": 1800.0
+ },
"s3": {
"bucket": null,
"region": null,
diff --git a/openviking/storage/transaction/__init__.py b/openviking/storage/transaction/__init__.py
index 93e772ac0..99de417b1 100644
--- a/openviking/storage/transaction/__init__.py
+++ b/openviking/storage/transaction/__init__.py
@@ -7,8 +7,4 @@ Path-lock management has been moved to the Rust ragfs layer.
Python-side lock operations now go through RAGFSBindingClient.pathlock_* methods.
"""
-from openviking.storage.transaction.redo_log import RedoLog
-
-__all__ = [
- "RedoLog",
-]
+__all__: list[str] = []
diff --git a/openviking/storage/transaction/redo_log.py b/openviking/storage/transaction/redo_log.py
deleted file mode 100644
index 7631919c1..000000000
--- a/openviking/storage/transaction/redo_log.py
+++ /dev/null
@@ -1,59 +0,0 @@
-# Copyright (c) 2026 Beijing Volcano Engine Technology Co., Ltd.
-# SPDX-License-Identifier: AGPL-3.0
-"""Lightweight redo log for crash recovery of session_memory operations."""
-
-import json
-from typing import Any, Dict, List
-
-from openviking.pyagfs import AGFSSyncClientProtocol, AsyncAGFSClient
-from openviking_cli.utils.logger import get_logger
-
-logger = get_logger(__name__)
-
-_REDO_ROOT = "/local/_system/redo"
-
-
-class RedoLog:
- """Lightweight pending-task marker.
-
- Write a marker before the operation starts; delete it after success.
- On startup, scan for leftover markers and redo.
- """
-
- def __init__(self, agfs: AGFSSyncClientProtocol):
- self._async_agfs = AsyncAGFSClient(agfs)
-
- def _task_path(self, task_id: str) -> str:
- return f"{_REDO_ROOT}/{task_id}/redo.json"
-
- async def mark_done_async(self, task_id: str) -> None:
- """Delete the redo marker after a successful operation."""
- try:
- await self._async_agfs.rm(f"{_REDO_ROOT}/{task_id}", recursive=True)
- except Exception as e:
- logger.warning(f"Failed to clean redo marker {task_id}: {e}")
-
- async def list_pending_async(self) -> List[str]:
- """Return all pending task IDs (directories under _REDO_ROOT)."""
- try:
- entries = await self._async_agfs.ls(_REDO_ROOT)
- if not isinstance(entries, list):
- return []
- return [
- e["name"]
- for e in entries
- if isinstance(e, dict) and e.get("isDir") and e.get("name") not in (".", "..")
- ]
- except Exception:
- return []
-
- async def read_async(self, task_id: str) -> Dict[str, Any]:
- """Read the info dict of a pending task."""
- try:
- content = await self._async_agfs.cat(self._task_path(task_id))
- if isinstance(content, bytes):
- content = content.decode("utf-8")
- return json.loads(content)
- except Exception as e:
- logger.warning(f"Failed to read redo info for {task_id}: {e}")
- return {}
diff --git a/openviking_cli/utils/config/agfs_config.py b/openviking_cli/utils/config/agfs_config.py
index feed25756..b86bc7f64 100644
--- a/openviking_cli/utils/config/agfs_config.py
+++ b/openviking_cli/utils/config/agfs_config.py
@@ -322,8 +322,12 @@ class AGFSPathLockConfig(BaseModel):
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.",
+ )
lock_expire_secs: float = Field(
- default=300.0,
+ default=1800.0,
description="Seconds before an unrefreshed lock token becomes stale.",
)
@@ -331,9 +335,11 @@ class AGFSPathLockConfig(BaseModel):
@model_validator(mode="after")
def validate_config(self):
- """Validate provider and stale-lock expiry."""
+ """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 059b1e4a6..558365f23 100644
--- a/openviking_cli/utils/config/storage_config.py
+++ b/openviking_cli/utils/config/storage_config.py
@@ -63,6 +63,44 @@ 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:
+ logger.warning(
+ "StorageConfig: 'transaction.lock_timeout' is deprecated and ignored because "
+ "'storage.agfs.pathlock.lock_timeout_secs' is set."
+ )
+
+ if (
+ "lock_expire" in self.transaction.model_fields_set
+ and "lock_expire_secs" not in self.agfs.pathlock.model_fields_set
+ ):
+ self.agfs.pathlock.lock_expire_secs = self.transaction.lock_expire
+ logger.warning(
+ "StorageConfig: 'transaction.lock_expire' is deprecated. "
+ "Mapped to 'storage.agfs.pathlock.lock_expire_secs'."
+ )
+ elif "lock_expire" in self.transaction.model_fields_set:
+ logger.warning(
+ "StorageConfig: 'transaction.lock_expire' is deprecated and ignored because "
+ "'storage.agfs.pathlock.lock_expire_secs' is set."
+ )
+
+ if "redo_recovery_enabled" in self.transaction.model_fields_set:
+ logger.warning(
+ "StorageConfig: 'transaction.redo_recovery_enabled' is deprecated and ignored. "
+ "Session commit phase-2 recovery now resumes from the persistent "
+ "'session_commit' queue."
+ )
+
if self.agfs.path is not None:
logger.warning(
f"StorageConfig: 'agfs.path' is deprecated and will be ignored. "
diff --git a/openviking_cli/utils/config/transaction_config.py b/openviking_cli/utils/config/transaction_config.py
index ead027358..97e76acd2 100644
--- a/openviking_cli/utils/config/transaction_config.py
+++ b/openviking_cli/utils/config/transaction_config.py
@@ -4,36 +4,35 @@ from pydantic import BaseModel, Field
class TransactionConfig(BaseModel):
- """Configuration for the transaction mechanism.
+ """Deprecated compatibility settings for legacy transaction fields.
- By default, lock acquisition does not wait (``lock_timeout=0``): if a
- conflicting lock is held the operation fails immediately with
- ``LockAcquisitionError``. Set ``lock_timeout`` to a positive value to
- allow the caller to block and retry for up to that many seconds.
+ Prefer ``storage.agfs.pathlock`` for active PathLock configuration.
"""
lock_timeout: float = Field(
default=0.0,
description=(
- "Path lock acquisition timeout (seconds). "
- "0 = fail immediately if locked (default). "
- "> 0 = wait/retry up to this many seconds before raising LockAcquisitionError."
+ "Deprecated compatibility field. "
+ "Use storage.agfs.pathlock.lock_timeout_secs instead. "
+ "When the new field is unset, this value is mapped to it."
),
)
lock_expire: float = Field(
default=1800.0,
description=(
- "Lock inactivity threshold (seconds). "
- "Locks not refreshed within this window are treated as stale and reclaimed."
+ "Deprecated compatibility field. "
+ "Use storage.agfs.pathlock.lock_expire_secs instead. "
+ "When the new field is unset, this value is mapped to it."
),
)
redo_recovery_enabled: bool = Field(
default=True,
description=(
- "Enable session commit phase-2 crash-recovery redo. "
- "When false, pending redo markers are not written and startup redo recovery is skipped."
+ "Deprecated compatibility flag for the legacy session commit phase-2 redo recovery. "
+ "Ignored in the current implementation, which resumes phase-2 work from the "
+ "persistent session_commit queue."
),
)
diff --git a/tests/misc/test_config_validation.py b/tests/misc/test_config_validation.py
index dccbfcffa..3f1efeea9 100644
--- a/tests/misc/test_config_validation.py
+++ b/tests/misc/test_config_validation.py
@@ -586,7 +586,8 @@ 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": 300.0,
+ "lock_expire_secs": 1800.0,
+ "lock_timeout_secs": 0.0,
},
}
@@ -606,6 +607,8 @@ 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/transaction/test_redo_log.py b/tests/transaction/test_redo_log.py
deleted file mode 100644
index 9feef74ea..000000000
--- a/tests/transaction/test_redo_log.py
+++ /dev/null
@@ -1,24 +0,0 @@
-# Copyright (c) 2026 Beijing Volcano Engine Technology Co., Ltd.
-# SPDX-License-Identifier: AGPL-3.0
-"""Tests for RedoLog crash recovery."""
-
-
-import pytest
-
-from openviking.storage.transaction.redo_log import RedoLog
-
-
-def redo(agfs_client):
- return RedoLog(agfs_client)
-
-
-class TestRedoLogBasic:
- async def test_read_nonexistent_returns_empty(self, redo):
- result = await redo.read_async("nonexistent-task-id")
- assert result == {}
-
- async def test_list_pending_empty(self, redo):
- # Should not crash even if _REDO_ROOT doesn't exist yet
- pending = await redo.list_pending_async()
- assert isinstance(pending, list)