Skip to content

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

16.8 KB
Raw Blame
# Copyright (c) 2026 Beijing Volcano Engine Technology Co., Ltd.
# SPDX-License-Identifier: AGPL-3.0
"""Filesystem endpoints for OpenViking HTTP Server."""

from typing import Any, Literal, Optional

from fastapi import APIRouter, Body, Depends, Query
from pydantic import BaseModel

from openviking.core.namespace import context_type_for_uri
from openviking.core.namespace_policy import namespace_policy_for_uri
from openviking.core.path_variables import resolve_path_variables
from openviking.core.uri_validation import validate_request_viking_uri
from openviking.pyagfs.exceptions import AGFSClientError, AGFSNotFoundError
from openviking.server.auth import get_request_context
from openviking.server.dependencies import get_service
from openviking.server.error_mapping import map_exception
from openviking.server.identity import RequestContext
from openviking.server.models import ListingResponse, Response
from openviking.server.routers.content import SetTagsRequest
from openviking.server.routers.content import set_tags as content_set_tags
from openviking.storage.acl import AclSpec
from openviking.storage.expr import And, Eq, In
from openviking.storage.vector_ids import is_vector_record_id
from openviking.storage.vikingdb_manager import VikingDBManagerProxy
from openviking.ttl.wiring import attach_expires_at
from openviking.utils.tags import normalize_search_tags
from openviking_cli.exceptions import NotFoundError

router = APIRouter(prefix="/api/v1/fs", tags=["filesystem"])


_ATTR_INDEX_FIELDS = ["level", "search_tags"]


def _clean_memory_attrs(raw: str) -> dict[str, Any]:
    from openviking.session.memory.utils.memory_file_utils import MemoryFileUtils

    mf = MemoryFileUtils.read(raw)
    attrs: dict[str, Any] = mf.to_metadata()
    attrs.pop("content", None)
    return attrs


async def _tags_attr(service: Any, uri: str, ctx: RequestContext, *, is_dir: bool) -> list[str]:
    vikingdb_manager = getattr(service, "vikingdb_manager", None)
    if not vikingdb_manager:
        return []

    # Tags are written per level (see ContentWriteCoordinator.set_tags): a
    # directory carries them on its L0/L1 summary records, while a file carries
    # them on its L2 content record. Mirror that here so the exact node's tags
    # are read back instead of unrelated records. Eq("uri", ...) compiles to an
    # exact path match (-d=0), avoiding prefix/subtree matches over the path field.
    levels = [0, 1] if is_dir else [2]
    proxy = VikingDBManagerProxy(vikingdb_manager, ctx)
    records = await proxy.filter(
        filter=And([Eq("uri", uri), In("level", levels)]),
        limit=10,
        output_fields=_ATTR_INDEX_FIELDS,
    )
    records = sorted(records, key=lambda item: item.get("level", 99))
    tags: list[str] = []
    for record in records:
        for tag in normalize_search_tags(record.get("search_tags"), discard_invalid=True):
            if tag not in tags:
                tags.append(tag)
    return tags


@router.get("/ls")
async def ls(
    uri: str = Query(..., description="Viking URI"),
    simple: bool = Query(False, description="Return only relative path list"),
    recursive: bool = Query(False, description="List all subdirectories recursively"),
    output: str = Query("agent", description="Output format: original or agent"),
    abs_limit: int = Query(256, description="Abstract limit (only for agent output)"),
    include_abstract: Optional[bool] = Query(
        None, description="Include directory L0 abstracts; defaults to the output format"
    ),
    include_overview: Optional[bool] = Query(None, description="Include directory L1 overviews"),
    overview_limit: int = Query(4000, ge=1, description="Maximum overview length"),
    show_all_hidden: bool = Query(False, description="List all hidden files, like -a"),
    node_limit: int = Query(1000, description="Maximum number of nodes to list"),
    offset: int = Query(0, ge=0, description="Number of visible nodes to skip"),
    limit: Optional[int] = Query(None, ge=1, description="Alias for node_limit"),
    sort_by: Optional[Literal["name", "mtime"]] = Query(
        None,
        description="Sort directory and file groups before applying node_limit",
    ),
    sort_order: Literal["asc", "desc"] = Query("asc", description="Sort direction"),
    extra_fields: Optional[list[str]] = Query(
        None, description="Extra fields to include: locked, id, count"
    ),
    tags: list[str] | None = Query(None, description="Only include entries matching all k=v tags"),
    include_tags: bool = Query(False, description="Include tags in each entry"),
    _ctx: RequestContext = Depends(get_request_context),
):
    """List directory contents."""
    service = get_service()
    actual_node_limit = limit if limit is not None else node_limit
    # Resolve path variables
    uri = validate_request_viking_uri(resolve_path_variables(uri), _ctx)
    try:
        page = await service.fs.ls(
            uri,
            ctx=_ctx,
            recursive=recursive,
            simple=simple,
            output=output,
            abs_limit=abs_limit,
            include_abstract=include_abstract,
            include_overview=include_overview,
            overview_limit=overview_limit,
            show_all_hidden=show_all_hidden,
            node_limit=actual_node_limit,
            offset=offset,
            sort_by=sort_by,
            sort_order=sort_order,
            extra_fields=extra_fields,
            tags=tags,
            include_tags=include_tags,
        )
    except AGFSNotFoundError:
        raise NotFoundError(uri, "file")
    except AGFSClientError as e:
        mapped = map_exception(e, resource=uri, resource_type="file")
        if mapped is not None:
            raise mapped from e
        raise
    await attach_expires_at(page.entries, _ctx)
    return ListingResponse(status="ok", result=page.entries, has_more=page.has_more)


@router.get("/tree")
async def tree(
    uri: str = Query(..., description="Viking URI"),
    output: str = Query("agent", description="Output format: original or agent"),
    abs_limit: int = Query(256, description="Maximum returned abstract length"),
    include_abstract: Optional[bool] = Query(
        None, description="Include directory L0 abstracts; defaults to the output format"
    ),
    include_overview: Optional[bool] = Query(None, description="Include directory L1 overviews"),
    overview_limit: int = Query(4000, ge=1, description="Maximum overview length"),
    show_all_hidden: bool = Query(False, description="List all hidden files, like -a"),
    directories_only: bool = Query(False, description="Only include directory entries"),
    node_limit: int = Query(1000, description="Maximum number of nodes to list"),
    offset: int = Query(0, ge=0, description="Number of visible nodes to skip"),
    limit: Optional[int] = Query(None, ge=1, description="Alias for node_limit"),
    level_limit: int = Query(3, description="Maximum depth level to traverse"),
    extra_fields: Optional[list[str]] = Query(
        None, description="Extra fields to include: locked, id, count"
    ),
    tags: list[str] | None = Query(None, description="Only include entries matching all k=v tags"),
    include_tags: bool = Query(False, description="Include tags in each entry"),
    _ctx: RequestContext = Depends(get_request_context),
):
    """Get directory tree."""
    service = get_service()
    actual_node_limit = limit if limit is not None else node_limit
    # Resolve path variables
    uri = validate_request_viking_uri(resolve_path_variables(uri), _ctx)
    try:
        page = await service.fs.tree(
            uri,
            ctx=_ctx,
            output=output,
            abs_limit=abs_limit,
            include_abstract=include_abstract,
            include_overview=include_overview,
            overview_limit=overview_limit,
            show_all_hidden=show_all_hidden,
            directories_only=directories_only,
            node_limit=actual_node_limit,
            level_limit=level_limit,
            offset=offset,
            extra_fields=extra_fields,
            tags=tags,
            include_tags=include_tags,
        )
    except AGFSNotFoundError:
        raise NotFoundError(uri, "file")
    except AGFSClientError as e:
        mapped = map_exception(e, resource=uri, resource_type="file")
        if mapped is not None:
            raise mapped from e
        raise
    await attach_expires_at(page.entries, _ctx)
    return ListingResponse(status="ok", result=page.entries, has_more=page.has_more)


@router.get("/stat")
async def stat(
    uri: str = Query(..., description="Viking URI or vector record id (32-char hex)"),
    _ctx: RequestContext = Depends(get_request_context),
):
    """Get resource status."""
    service = get_service()
    # If the argument is a raw 32-hex vector record id, skip URI validation
    # (id lookup + access check happens inside VikingFS.stat).
    if is_vector_record_id(uri):
        resolved = uri
    else:
        resolved = validate_request_viking_uri(resolve_path_variables(uri), _ctx)
    try:
        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)
        payload = {**result, "uri": response_uri}
        await attach_expires_at([payload], _ctx)
        return Response(status="ok", result=payload)
    except AGFSNotFoundError:
        raise NotFoundError(uri, "file")
    except AGFSClientError as e:
        mapped = map_exception(e, resource=uri, resource_type="file")
        if mapped is not None:
            raise mapped from e
        raise
    except Exception as exc:
        mapped = map_exception(exc, resource=uri)
        if mapped is not None:
            raise mapped from exc
        raise


@router.get("/attrs")
async def attrs(
    uri: str = Query(..., description="Viking URI"),
    _ctx: RequestContext = Depends(get_request_context),
):
    """Get logical extended attributes for a URI."""
    service = get_service()
    uri = validate_request_viking_uri(resolve_path_variables(uri), _ctx)
    try:
        stat_result = await service.fs.stat(uri, ctx=_ctx, skip_count=True)
        namespace_policy = namespace_policy_for_uri(uri)
        tags = (
            await _tags_attr(service, uri, _ctx, is_dir=stat_result.get("isDir", False))
            if namespace_policy.supports_tags
            else []
        )
        result = {
            "uri": uri,
            "context_type": context_type_for_uri(uri),
            "attrs": {"tags": tags},
        }
        if result["context_type"] == "memory" and not stat_result.get("isDir", False):
            result["attrs"]["memory"] = _clean_memory_attrs(await service.fs.read(uri, ctx=_ctx))
        return Response(status="ok", result=result)
    except AGFSNotFoundError:
        raise NotFoundError(uri, "file")
    except AGFSClientError as e:
        mapped = map_exception(e, resource=uri, resource_type="file")
        if mapped is not None:
            raise mapped from e
        raise
    except Exception as exc:
        mapped = map_exception(exc, resource=uri)
        if mapped is not None:
            raise mapped from exc
        raise


@router.post("/attrs/set_tags")
async def attrs_set_tags(
    request: SetTagsRequest = Body(...),
    _ctx: RequestContext = Depends(get_request_context),
):
    """Set explicit k=v retrieval tags metadata for a file or directory."""
    return await content_set_tags(request, _ctx)


class MkdirRequest(BaseModel):
    """Request model for mkdir."""

    uri: str
    description: Optional[str] = None
    acl: AclSpec | None = None


@router.post("/mkdir")
async def mkdir(
    request: MkdirRequest,
    _ctx: RequestContext = Depends(get_request_context),
):
    """Create directory."""
    service = get_service()
    # Resolve path variables
    uri = validate_request_viking_uri(resolve_path_variables(request.uri), _ctx)
    try:
        await service.fs.mkdir(
            uri,
            ctx=_ctx,
            description=request.description,
            **({"acl": request.acl} if request.acl is not None else {}),
        )
    except AGFSClientError as e:
        mapped = map_exception(e, resource=uri, resource_type="file")
        if mapped is not None:
            raise mapped from e
        raise
    return Response(status="ok", result={"uri": uri})


@router.delete("")
async def rm(
    uri: str = Query(..., description="Viking URI"),
    recursive: bool = Query(False, description="Remove recursively"),
    wait: bool = Query(False, description="Wait for semantic refresh to complete"),
    timeout: Optional[float] = Query(
        None,
        deprecated=True,
        description="Deprecated compatibility parameter; accepted and ignored.",
    ),
    _ctx: RequestContext = Depends(get_request_context),
):
    """Remove resource."""
    service = get_service()
    # Resolve path variables
    uri = validate_request_viking_uri(resolve_path_variables(uri), _ctx)
    try:
        result = await service.fs.rm(uri, ctx=_ctx, recursive=recursive, wait=wait)
    except AGFSNotFoundError:
        raise NotFoundError(uri, "file")
    except AGFSClientError as e:
        mapped = map_exception(e, resource=uri, resource_type="file")
        if mapped is not None:
            raise mapped from e
        raise
    except Exception as exc:
        mapped = map_exception(exc, resource=uri)
        if mapped is not None:
            raise mapped from exc
        raise
    # Build response with uri and estimated_deleted_count
    response_result = {"uri": uri}
    if isinstance(result, dict) and "estimated_deleted_count" in result:
        response_result["estimated_deleted_count"] = result["estimated_deleted_count"]
    if isinstance(result, dict) and "memory_cleanup" in result:
        response_result["memory_cleanup"] = result["memory_cleanup"]
    if isinstance(result, dict) and "semantic_root_uri" in result:
        response_result["semantic_root_uri"] = result["semantic_root_uri"]
    if isinstance(result, dict) and "semantic_status" in result:
        response_result["semantic_status"] = result["semantic_status"]
    if isinstance(result, dict) and "queue_status" in result:
        response_result["queue_status"] = result["queue_status"]
    if isinstance(result, dict) and "task_id" in result:
        response_result["task_id"] = result["task_id"]
    return Response(status="ok", result=response_result)


class MvRequest(BaseModel):
    """Request model for mv."""

    from_uri: str
    to_uri: str


class CpRequest(BaseModel):
    """Request model for cp."""

    from_uri: str
    to_uri: str
    recursive: bool = False


@router.post("/cp")
async def cp(
    request: CpRequest,
    _ctx: RequestContext = Depends(get_request_context),
):
    """Copy a file or directory together with its vector records."""
    service = get_service()
    from_uri = validate_request_viking_uri(
        resolve_path_variables(request.from_uri), _ctx, field_name="from_uri"
    )
    to_uri = validate_request_viking_uri(
        resolve_path_variables(request.to_uri), _ctx, field_name="to_uri"
    )
    try:
        result = await service.fs.cp(
            from_uri,
            to_uri,
            recursive=request.recursive,
            ctx=_ctx,
        )
    except AGFSNotFoundError:
        raise NotFoundError(from_uri, "file")
    except AGFSClientError as exc:
        mapped = map_exception(exc, resource=from_uri, resource_type="file")
        if mapped is not None:
            raise mapped from exc
        raise
    except Exception as exc:
        mapped = map_exception(exc, resource=from_uri)
        if mapped is not None:
            raise mapped from exc
        raise

    response_result = dict(result or {})
    response_result.setdefault("from", from_uri)
    response_result.setdefault("to", to_uri)
    response_result.setdefault("recursive", request.recursive)
    return Response(status="ok", result=response_result)


@router.post("/mv")
async def mv(
    request: MvRequest,
    _ctx: RequestContext = Depends(get_request_context),
):
    """Move resource."""
    service = get_service()
    # Resolve path variables
    from_uri = validate_request_viking_uri(
        resolve_path_variables(request.from_uri), _ctx, field_name="from_uri"
    )
    to_uri = validate_request_viking_uri(
        resolve_path_variables(request.to_uri), _ctx, field_name="to_uri"
    )
    try:
        await service.fs.mv(from_uri, to_uri, ctx=_ctx)
    except AGFSNotFoundError:
        raise NotFoundError(from_uri, "file")
    except AGFSClientError as e:
        mapped = map_exception(e, resource=from_uri, resource_type="file")
        if mapped is not None:
            raise mapped from e
        raise
    except Exception as exc:
        mapped = map_exception(exc, resource=from_uri)
        if mapped is not None:
            raise mapped from exc
        raise
    return Response(status="ok", result={"from": from_uri, "to": to_uri})