Skip to content

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

perf(fs): query path lock status on demand (#4837)

Jiahui Zhouda5f6b842e18
diff --git a/openviking/server/routers/filesystem.py b/openviking/server/routers/filesystem.py
index 8c9320dbc..c44ed7463 100644
--- a/openviking/server/routers/filesystem.py
+++ b/openviking/server/routers/filesystem.py
@@ -180,7 +180,7 @@ async def stat(
else:
resolved = validate_request_viking_uri(resolve_path_variables(uri), _ctx)
try:
- result = await service.fs.stat(resolved, ctx=_ctx)
+ result = await service.fs.stat(resolved, ctx=_ctx, include_lock_status=True)
# URI requests use the canonical validated URI. ID requests are resolved
# inside VikingFS, which returns the corresponding canonical URI.
response_uri = result.get("uri", resolved)
diff --git a/openviking/service/fs_service.py b/openviking/service/fs_service.py
index 5943930ba..d0d712884 100644
--- a/openviking/service/fs_service.py
+++ b/openviking/service/fs_service.py
@@ -928,10 +928,21 @@ class FSService:
result, ctx, None, include_tags or "tags" in (extra_fields or [])
)
- async def stat(self, uri: str, ctx: RequestContext, skip_count: bool = False) -> Dict[str, Any]:
+ async def stat(
+ self,
+ uri: str,
+ ctx: RequestContext,
+ skip_count: bool = False,
+ include_lock_status: bool = False,
+ ) -> Dict[str, Any]:
"""Get resource status."""
viking_fs = self._ensure_initialized()
- return await viking_fs.stat(uri, ctx=ctx, skip_count=skip_count)
+ return await viking_fs.stat(
+ uri,
+ ctx=ctx,
+ skip_count=skip_count,
+ include_lock_status=include_lock_status,
+ )
async def ensure_write_access(self, uri: str, ctx: RequestContext) -> None:
"""Validate write access without mutating the target."""
diff --git a/openviking/storage/viking_fs/_ops.py b/openviking/storage/viking_fs/_ops.py
index d289d514b..f1be0e35a 100644
--- a/openviking/storage/viking_fs/_ops.py
+++ b/openviking/storage/viking_fs/_ops.py
@@ -995,15 +995,20 @@ class _OpsMixin:
return resolved
async def stat(
- self, uri: str, ctx: Optional[RequestContext] = None, skip_count: bool = False
+ self,
+ uri: str,
+ ctx: Optional[RequestContext] = None,
+ skip_count: bool = False,
+ include_lock_status: bool = False,
) -> Dict[str, Any]:
"""
File/directory information.
- example: {'name': 'resources', 'size': 128, 'mode': 2147484141, 'modTime': '2026-02-10T21:26:02.934376379+08:00', 'isDir': True, 'isLocked': False, 'count': 42, 'meta': {'Name': 'localfs', 'Type': 'local', 'Content': {'local_path': '...'}}}
+ example: {'name': 'resources', 'size': 128, 'mode': 2147484141, 'modTime': '2026-02-10T21:26:02.934376379+08:00', 'isDir': True, 'count': 42, 'meta': {'Name': 'localfs', 'Type': 'local', 'Content': {'local_path': '...'}}}
Extra fields:
- isLocked (bool): Whether the path is currently held by a path lock
+ isLocked (bool): When ``include_lock_status`` is True, whether the
+ path is currently held by a path lock
(either the path itself or any ancestor directory). Returns
False when the pathlock system is not enabled or the lookup
fails.
@@ -1023,6 +1028,9 @@ class _OpsMixin:
skip_count: If True, skip the vector_store.count() call for directories.
Use this when the count field is not needed (e.g. in grep) to avoid
an extra VikingDB API call.
+ include_lock_status: If True, include ``isLocked`` in the result.
+ Leave disabled for internal metadata checks to avoid the extra
+ PathLock filesystem lookup.
"""
real_ctx = self._ctx_or_default(ctx)
uri = await self.resolve_uri(uri, real_ctx)
@@ -1045,18 +1053,21 @@ class _OpsMixin:
else:
if self._is_session_root_uri(uri):
now = datetime.now(timezone.utc).isoformat()
- return {
+ result = {
"name": "session",
"size": 0,
"mode": 0o755,
"modTime": now,
"isDir": True,
- "isLocked": False,
}
+ if include_lock_status:
+ result["isLocked"] = False
+ return result
raise NotFoundError(uri, "file") from last_not_found
if isinstance(result, dict):
result["uri"] = uri
- result["isLocked"] = await self._is_path_locked_async(path)
+ if include_lock_status:
+ result["isLocked"] = await self._is_path_locked_async(path)
# Add deterministic vector record id for files (level 2).
# This matches the ID used in VikingDB so callers can cross-reference
# vector records without an extra lookup.
diff --git a/tests/server/test_filesystem_router.py b/tests/server/test_filesystem_router.py
index 48b865c6e..8aaf19eca 100644
--- a/tests/server/test_filesystem_router.py
+++ b/tests/server/test_filesystem_router.py
@@ -271,8 +271,8 @@ async def test_http_stat_returns_canonical_request_uri(monkeypatch):
seen = {}
request_context = RequestContext(user=UserIdentifier("acct", "alice"), role=Role.USER)
- async def fake_stat(uri, ctx=None):
- seen.update(uri=uri, ctx=ctx)
+ async def fake_stat(uri, ctx=None, include_lock_status=False):
+ seen.update(uri=uri, ctx=ctx, include_lock_status=include_lock_status)
return {
"name": "notes.md",
"size": 12,
@@ -302,6 +302,7 @@ async def test_http_stat_returns_canonical_request_uri(monkeypatch):
assert response.json()["result"]["uri"] == "viking://user/alice/resources/notes.md"
assert seen["uri"] == "viking://user/alice/resources/notes.md"
assert seen["ctx"].user.user_id == "alice"
+ assert seen["include_lock_status"] is True
@pytest.mark.asyncio
@@ -310,8 +311,8 @@ async def test_http_stat_by_record_id_returns_resolved_uri(monkeypatch):
resolved_uri = "viking://user/alice/resources/notes.md"
seen = {}
- async def fake_stat(uri, ctx=None):
- seen.update(uri=uri, ctx=ctx)
+ async def fake_stat(uri, ctx=None, include_lock_status=False):
+ seen.update(uri=uri, ctx=ctx, include_lock_status=include_lock_status)
return {
"uri": resolved_uri,
"name": "notes.md",
@@ -341,6 +342,7 @@ async def test_http_stat_by_record_id_returns_resolved_uri(monkeypatch):
assert response.status_code == 200, response.text
assert response.json()["result"]["uri"] == resolved_uri
assert seen["uri"] == record_id
+ assert seen["include_lock_status"] is True
@pytest.mark.asyncio
diff --git a/tests/service/test_fs_service.py b/tests/service/test_fs_service.py
index e378ff8f6..aefcb28dc 100644
--- a/tests/service/test_fs_service.py
+++ b/tests/service/test_fs_service.py
@@ -54,20 +54,27 @@ class _FakeVikingFS:
@pytest.mark.asyncio
-async def test_stat_forwards_skip_count_without_changing_default(request_context):
+async def test_stat_forwards_optional_fields_without_changing_defaults(request_context):
viking_fs = SimpleNamespace(stat=AsyncMock(return_value={"isDir": True}))
service = FSService(viking_fs=viking_fs)
- await service.stat("viking://resources", request_context, skip_count=True)
+ await service.stat(
+ "viking://resources",
+ request_context,
+ skip_count=True,
+ include_lock_status=True,
+ )
await service.stat("viking://resources", request_context)
assert viking_fs.stat.await_args_list[0].kwargs == {
"ctx": request_context,
"skip_count": True,
+ "include_lock_status": True,
}
assert viking_fs.stat.await_args_list[1].kwargs == {
"ctx": request_context,
"skip_count": False,
+ "include_lock_status": False,
}
diff --git a/tests/storage/test_viking_fs_tree.py b/tests/storage/test_viking_fs_tree.py
index 885b084bc..8adcc3831 100644
--- a/tests/storage/test_viking_fs_tree.py
+++ b/tests/storage/test_viking_fs_tree.py
@@ -28,6 +28,50 @@ def _default_ctx() -> RequestContext:
return RequestContext(user=UserIdentifier.the_default_user(), role=Role.ROOT)
+async def test_stat_queries_lock_status_only_when_requested(monkeypatch, fs):
+ path = "/local/default/resources/example.md"
+ lock_queries = []
+
+ async def resolve_uri(uri, _ctx):
+ return uri
+
+ async def ensure_access(_uri, _ctx):
+ return None
+
+ async def read_path_visible(_uri, _path, _primary_path, _ctx):
+ return True
+
+ async def stat_path(_path):
+ return {"name": "example.md", "isDir": False}
+
+ async def is_path_locked(queried_path):
+ lock_queries.append(queried_path)
+ return True
+
+ monkeypatch.setattr(fs, "resolve_uri", resolve_uri)
+ monkeypatch.setattr(fs, "_ensure_access", ensure_access)
+ monkeypatch.setattr(fs, "_uri_to_path", lambda _uri, **_kwargs: path)
+ monkeypatch.setattr(fs, "_read_paths", lambda _uri, **_kwargs: [path])
+ monkeypatch.setattr(fs, "_read_path_visible", read_path_visible)
+ monkeypatch.setattr(fs._async_agfs, "stat", stat_path)
+ monkeypatch.setattr(fs, "_is_path_locked_async", is_path_locked)
+
+ result = await fs.stat("viking://resources/example.md", ctx=_default_ctx())
+
+ assert "isLocked" not in result
+ assert lock_queries == []
+
+ result = await fs.stat(
+ "viking://resources/example.md",
+ ctx=_default_ctx(),
+ include_lock_status=True,
+ )
+
+ assert result["isLocked"] is True
+ assert lock_queries == [path]
+
+
def test_viking_fs_no_longer_exposes_python_encryption_api(fs: VikingFS):
"""VikingFS should not expose Python-side encryption helpers after ragfs migration."""
assert not hasattr(fs, "_encrypt_content")