Self-evolving Context Database for AI Agents. Unify Agent Memory, Knowledge RAG and Skills.
Python agent-contextagent-memoryagent-pluginsagentic-ragcontext-databasedsh-pluginknowledge-basememorymemory-managementself-evolvingvector-database
# Copyright (c) 2026 Beijing Volcano Engine Technology Co., Ltd.
# SPDX-License-Identifier: AGPL-3.0
"""AGFS Python Binding Tests for VikingFS interface
Tests the python binding mode of VikingFS which directly uses AGFS implementation
without HTTP server.
"""
import asyncio
import os
import shutil
import uuid
from concurrent.futures import ThreadPoolExecutor
import pytest
from openviking.storage.viking_fs import init_viking_fs
from openviking.utils.resource_processor import ResourceProcessor
from openviking_cli.utils.config.agfs_config import AGFSConfig
# Direct configuration for testing
AGFS_CONF = AGFSConfig(path="/tmp/ov-test", backend="local")
# clean up test directory if it exists
if os.path.exists(AGFS_CONF.path):
shutil.rmtree(AGFS_CONF.path)
@pytest.fixture(scope="module")
async def viking_fs_binding_instance():
"""Initialize VikingFS with binding mode."""
from openviking.utils.agfs_utils import RagfsBindingConfig, create_agfs_client
# Create AGFS client
agfs_client = create_agfs_client(RagfsBindingConfig(agfs=AGFS_CONF))
vfs = init_viking_fs(agfs=agfs_client)
# make sure default/temp directory exists
await vfs.mkdir("viking://temp/", exist_ok=True)
yield vfs
@pytest.mark.asyncio
class TestVikingFSBindingLocal:
"""Test VikingFS operations with binding mode (local backend)."""
async def test_native_metrics_and_legacy_stats(self, viking_fs_binding_instance):
"""Use the binding fixture to check flat metrics and legacy stats; return None."""
client = viking_fs_binding_instance._async_agfs
lease = await client.pathlock_acquire_tree(
f"/local/default/temp/metrics_scan_{uuid.uuid4().hex}"
)
try:
metrics = await client.run("metrics")
finally:
await client.pathlock_release(lease)
scan = next(m for m in metrics if m["name"] == "lock_descendant_scan_duration_seconds")
legacy_count = next(m for m in metrics if m["name"] == "lock_descendant_scans_total")
legacy_sum = next(
m for m in metrics if m["name"] == "lock_descendant_scan_duration_seconds_total"
)
assert scan["count"] == legacy_count["value"] > 0
assert scan["sum"] == legacy_sum["value"]
shapes = {
"counter": {"value", "scale"},
"gauge": {"value"},
"histogram": {"bucket_bounds", "bucket_counts", "count", "sum", "scale"},
}
assert {m["type"] for m in metrics} == set(shapes)
for metric in metrics:
assert set(metric) == {"name", "labels", "type"} | shapes[metric["type"]]
assert not metric["name"].startswith("openviking_")
assert set(metric["labels"]) <= {
"plugin",
"operation",
"status",
"kind",
"result",
"source",
"event",
"route",
}
if metric["type"] == "histogram":
assert metric["count"] > 0
assert len(metric["bucket_counts"]) == len(metric["bucket_bounds"]) + 1
assert metric["bucket_bounds"][-1] > 404261.58497 * 1e9
assert sum(metric["bucket_counts"]) == metric["count"]
assert metric["scale"] == 1e-9 and type(metric["sum"]) is int
else:
assert type(metric["value"]) is (int if metric["type"] == "counter" else float)
all_stats = await client.run("get_stats")
assert set(all_stats) == {"mounts"} and all_stats["mounts"]
scoped = await client.run("get_stats", path=all_stats["mounts"][0]["path"])
for mount in [*all_stats["mounts"], scoped]:
assert set(mount) == {"path", "plugin", "stats"}
for stats in mount["stats"]["operations"].values():
assert set(stats) == {
"count",
"total_time_us",
"min_time_us",
"max_time_us",
"avg_time_us",
}
assert all(
type(value) is (float if key == "avg_time_us" else int)
for key, value in stats.items()
)
if stats["count"] == 0:
assert stats["min_time_us"] == 2**64 - 1 and stats["avg_time_us"] == 0.0
async def test_file_operations(self, viking_fs_binding_instance):
"""Test VikingFS file operations: read, write, ls, stat."""
vfs = viking_fs_binding_instance
test_filename = f"binding_file_{uuid.uuid4().hex}.txt"
test_content = "Hello VikingFS Binding! " + uuid.uuid4().hex
test_uri = f"viking://temp/{test_filename}"
await vfs.write(test_uri, test_content)
stat_info = await vfs.stat(test_uri)
assert stat_info["name"] == test_filename
assert not stat_info["isDir"]
entries = await vfs.ls("viking://temp/")
assert any(e["name"] == test_filename for e in entries)
page_dir_uri = f"viking://temp/page_{uuid.uuid4().hex}/"
await vfs.mkdir(page_dir_uri)
for name in ("a.txt", "b.txt", "c.txt"):
await vfs.write(f"{page_dir_uri}{name}", name)
page = await vfs.ls(
page_dir_uri,
output="original",
node_limit=1,
offset=1,
sort_by="name",
)
assert [entry["name"] for entry in page] == ["b.txt"]
read_data = await vfs.read(test_uri)
assert read_data.decode("utf-8") == test_content
await vfs.rm(page_dir_uri, recursive=True)
await vfs.rm(test_uri)
async def test_directory_operations(self, viking_fs_binding_instance):
"""Test VikingFS directory operations: mkdir, rm, ls, stat."""
vfs = viking_fs_binding_instance
test_dir = f"binding_dir_{uuid.uuid4().hex}"
test_dir_uri = f"viking://temp/{test_dir}/"
await vfs.mkdir(test_dir_uri)
stat_info = await vfs.stat(test_dir_uri)
assert stat_info["name"] == test_dir
assert stat_info["isDir"]
root_entries = await vfs.ls("viking://temp/")
assert any(e["name"] == test_dir and e["isDir"] for e in root_entries)
file_uri = f"{test_dir_uri}inner.txt"
await vfs.write(file_uri, "inner content")
await vfs.write(f"{test_dir_uri}z.txt", "second")
sub_entries = await vfs.ls(test_dir_uri)
assert any(e["name"] == "inner.txt" for e in sub_entries)
tree_page = await vfs.tree(
test_dir_uri,
output="original",
node_limit=1,
offset=1,
)
assert [entry["name"] for entry in tree_page] == ["z.txt"]
await vfs.rm(test_dir_uri, recursive=True)
root_entries = await vfs.ls("viking://temp/")
assert not any(e["name"] == test_dir for e in root_entries)
async def test_flat_file_lock_keeps_persisted_target_a_file(
self,
viking_fs_binding_instance,
):
"""An exact resource lock must not materialize a file target as a directory."""
vfs = viking_fs_binding_instance
unique = uuid.uuid4().hex
temp_uri = f"viking://temp/flat_lock_{unique}.md"
target_uri = f"viking://resources/flat_lock_{unique}.md"
target_path = vfs._uri_to_path(target_uri)
lease = None
try:
await vfs.write(temp_uri, "flat file content")
lease = await ResourceProcessor.acquire_resource_lock(
target_path,
uri=target_uri,
root_is_file=True,
)
await vfs.persist_temp_tree(
temp_uri,
target_uri,
lease_ref=lease,
)
stat_info = await vfs.stat(target_uri)
assert stat_info["isDir"] is False
assert await vfs.read(target_uri) == b"flat file content"
finally:
if lease is not None:
await vfs._async_agfs.pathlock_release(lease)
for uri in (temp_uri, target_uri):
if await vfs.exists(uri):
stat_info = await vfs.stat(uri)
await vfs.rm(uri, recursive=bool(stat_info.get("isDir")))
async def test_recursive_cp_uses_parent_tree_batch_lease(
self,
viking_fs_binding_instance,
):
"""A batch lease on distinct parents must cover all recursive copy operations."""
vfs = viking_fs_binding_instance
unique = uuid.uuid4().hex
source_uri = f"viking://temp/cp_source_{unique}"
target_uri = f"viking://resources/cp_target_{unique}"
try:
await vfs.mkdir("viking://resources/", exist_ok=True)
await vfs.mkdir(source_uri)
await vfs.mkdir(f"{source_uri}/empty")
await vfs.write(f"{source_uri}/data.bin", b"\x00\xff")
await vfs.cp(source_uri, target_uri, recursive=True)
assert (await vfs.stat(f"{target_uri}/empty"))["isDir"] is True
assert await vfs.read(f"{target_uri}/data.bin") == b"\x00\xff"
finally:
for uri in (source_uri, target_uri):
if await vfs.exists(uri):
await vfs.rm(uri, recursive=True)
async def test_borrowed_pathlock_cannot_release_via_raw_ref(self, viking_fs_binding_instance):
"""Reject borrowed lifecycle control through typed and raw lease refs."""
vfs = viking_fs_binding_instance
path = f"/local/default/temp/borrowed_release_{uuid.uuid4().hex}.txt"
owned = await vfs._async_agfs.pathlock_acquire_exact(path)
borrowed = await vfs._async_agfs.pathlock_as_borrowed(owned)
try:
with pytest.raises(ValueError):
await vfs._async_agfs.pathlock_release(borrowed)
with pytest.raises((TypeError, ValueError)):
await vfs._async_agfs.pathlock_release(borrowed["lease_ref"])
finally:
await vfs._async_agfs.pathlock_release(owned)
async def test_pathlock_adopt_rejects_forged_tree_coverage(self, viking_fs_binding_instance):
"""Reject handoff coverage that is stronger than the live token."""
vfs = viking_fs_binding_instance
path = f"/local/default/temp/handoff_forge_{uuid.uuid4().hex}.txt"
owned = await vfs._async_agfs.pathlock_acquire_exact(path)
handoff = await vfs._async_agfs.pathlock_to_handoff(owned)
handoff["covered_paths"] = [{"path": path, "kind": "tree"}]
adopted = None
try:
with pytest.raises(ValueError):
adopted = await vfs._async_agfs.pathlock_adopt(handoff)
finally:
if adopted is not None:
await vfs._async_agfs.pathlock_release(adopted)
await vfs._async_agfs.pathlock_release(owned)
async def test_pathlock_adopt_accepts_legacy_handle_id_handoff(
self, viking_fs_binding_instance
):
"""Accept legacy durable handoffs that use handle_id instead of owner_id."""
vfs = viking_fs_binding_instance
path = f"/local/default/temp/handoff_legacy_{uuid.uuid4().hex}.txt"
owned = await vfs._async_agfs.pathlock_acquire_exact(path)
handoff = await vfs._async_agfs.pathlock_to_handoff(owned)
legacy_handoff = {
"handle_id": handoff["owner_id"],
"lock_paths": handoff["lock_paths"],
}
adopted = None
try:
adopted = await vfs._async_agfs.pathlock_adopt(legacy_handoff)
assert adopted["owner_id"] == owned["owner_id"]
assert adopted["owned"] is True
finally:
if adopted is not None:
await vfs._async_agfs.pathlock_release(adopted)
await vfs._async_agfs.pathlock_release(owned)
async def test_pathlock_wait_and_cancel_release_resources(self, viking_fs_binding_instance):
"""Lock waits leave storage responsive; cancelled acquisitions release their lease."""
client = viking_fs_binding_instance._async_agfs
asyncio.get_running_loop().set_default_executor(ThreadPoolExecutor(max_workers=1))
path = f"/local/default/temp/wait_{uuid.uuid4().hex}"
owner = await client.pathlock_acquire_exact(path)
waiter = asyncio.create_task(client.pathlock_acquire_exact(path, timeout_secs=2))
try:
await asyncio.sleep(0.01)
await asyncio.wait_for(client.stat("/local"), timeout=0.5)
finally:
waiter.cancel()
await client.pathlock_release(owner)
with pytest.raises(asyncio.CancelledError):
await waiter
lease = await client.pathlock_acquire_exact(path)
await client.pathlock_release(lease)
async def test_tree_operations(self, viking_fs_binding_instance):
"""Test VikingFS tree operations."""
vfs = viking_fs_binding_instance
base_dir = f"binding_tree_test_{uuid.uuid4().hex}"
sub_dir = f"viking://temp/{base_dir}/a/b/"
file_uri = f"{sub_dir}leaf.txt"
await vfs.mkdir(sub_dir)
await vfs.write(file_uri, "leaf content")
entries = await vfs.tree(f"viking://temp/{base_dir}/")
assert any("leaf.txt" in e["uri"] for e in entries)
await vfs.rm(f"viking://temp/{base_dir}/", recursive=True)
async def test_glob_matches_deep_markdown_files(self, viking_fs_binding_instance):
"""Test glob recursively matches markdown files beyond tree's default depth."""
vfs = viking_fs_binding_instance
base_dir = f"binding_glob_test_{uuid.uuid4().hex}"
deep_dir_uri = f"viking://temp/{base_dir}/events/2023/05/08/"
deep_file_uri = f"{deep_dir_uri}entry.md"
await vfs.mkdir(deep_dir_uri)
await vfs.write(deep_file_uri, "# deep event")
result = await vfs.glob("**/*.md", uri=f"viking://temp/{base_dir}/")
assert deep_file_uri in result["matches"]
await vfs.rm(f"viking://temp/{base_dir}/", recursive=True)
async def test_binary_operations(self, viking_fs_binding_instance):
"""Test VikingFS binary file operations."""
vfs = viking_fs_binding_instance
test_filename = f"binding_binary_{uuid.uuid4().hex}.bin"
test_content = bytes([i % 256 for i in range(256)])
test_uri = f"viking://temp/{test_filename}"
await vfs.write(test_uri, test_content)
read_data = await vfs.read(test_uri)
assert read_data == test_content
await vfs.rm(test_uri)