Skip to content

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

14.3 KB
Raw Blame
# 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)