OpenRAG is a comprehensive, single package Retrieval-Augmented Generation platform built on Langflow, Docling, and Opensearch.
Python
"""
Unit tests for the public (API-key) file listing/search handlers.
The public files surface is served by two handler sets, all gated by
require_api_key_permission("knowledge:read:own"):
- api.v1.files.get_all_files → GET /v1/files/get_all (offset pagination)
- api.v2.files.list_files → GET /v2/files (cursor pagination)
- api.v2.files.search_files → GET /v2/files/search (cursor pagination)
Tests cover:
- All public handlers authenticate with require_api_key_permission, NOT
get_current_user
- The v2 public handlers forward every param to FileServiceV2 and delegate to
the internal handlers
- The public wrappers do not drift from the internal handler signatures
- 401 on OpenSearch auth errors, 400 on malformed after_key, 500 on unexpected
"""
import inspect
from unittest.mock import AsyncMock, MagicMock
import pytest
from fastapi import params as fastapi_params
from api.files import (
list_files as internal_list_files,
)
from api.files import (
search_files as internal_search_files,
)
from api.v1.files import get_all_files
from api.v2.files import list_files as list_files_public
from api.v2.files import search_files as search_files_public
from session_manager import User
# ---------------------------------------------------------------------------
# Auth-dependency introspection helpers
# ---------------------------------------------------------------------------
def _get_user_dependency(fn) -> object:
"""Return the raw dependency object wired to the `user` parameter of `fn`."""
sig = inspect.signature(fn)
user_param = sig.parameters.get("user")
assert user_param is not None, f"{fn.__name__} has no `user` parameter"
default = user_param.default
assert isinstance(default, fastapi_params.Depends), (
f"`user` default in {fn.__name__} is not a FastAPI Depends()"
)
return default.dependency
def _extract_permission(dep) -> str:
"""Extract the permission string from a require_api_key_permission closure."""
# require_api_key_permission(perm) returns a closure _dep whose __closure__
# holds exactly one cell: the `perm` string.
assert dep.__closure__ is not None, "dependency has no closure — not a permission closure"
perm_values = [cell.cell_contents for cell in dep.__closure__]
assert len(perm_values) == 1, (
f"Expected exactly one closure cell, got {len(perm_values)}: {perm_values}"
)
return perm_values[0]
# ---------------------------------------------------------------------------
# Route-level dependency tests
# ---------------------------------------------------------------------------
class TestAuthDependency:
@pytest.mark.parametrize(
"handler",
[get_all_files, list_files_public, search_files_public],
ids=["get_all_files", "list_files_public", "search_files_public"],
)
def test_public_handler_uses_require_api_key_permission(self, handler):
"""Every public handler must be gated by require_api_key_permission."""
dep = _get_user_dependency(handler)
perm = _extract_permission(dep)
assert perm == "knowledge:read:own", f"Expected 'knowledge:read:own', got '{perm}'"
def test_all_public_handlers_use_same_permission(self):
"""All public handlers must require the same permission — no divergence."""
perms = {
_extract_permission(_get_user_dependency(h))
for h in (get_all_files, list_files_public, search_files_public)
}
assert perms == {"knowledge:read:own"}
# ---------------------------------------------------------------------------
# Signature drift guard
# ---------------------------------------------------------------------------
def _query_params(fn) -> dict:
"""Parameter name -> annotation for every param except the auth `user`.
`file_service` is kept: internal and public handlers share the same
injected service, so it should stay identical too.
"""
return {
name: p.annotation for name, p in inspect.signature(fn).parameters.items() if name != "user"
}
class TestSignatureParity:
"""The public wrappers re-declare the query signature; guard against drift."""
def test_list_files_public_matches_internal(self):
assert _query_params(list_files_public) == _query_params(internal_list_files)
def test_search_files_public_matches_internal(self):
assert _query_params(search_files_public) == _query_params(internal_search_files)
def _make_user() -> User:
user = MagicMock(spec=User)
user.user_id = "test-user-id"
user.jwt_token = "test-jwt"
return user
def _make_file_service(result: dict) -> MagicMock:
svc = MagicMock()
svc.list_files = AsyncMock(return_value=result)
svc.search_files = AsyncMock(return_value=result)
return svc
_SAMPLE_RESPONSE = {
"files": [
{
"filename": "report.pdf",
"document_id": "doc-1",
"mimetype": "application/pdf",
"file_size": 12345,
"source_url": "",
"owner": "user-1",
"owner_name": "Alice",
"owner_email": "[email protected]",
"connector_type": "local",
"embedding_model": "text-embedding-3-small",
"embedding_dimensions": 1536,
"indexed_time": "2024-01-01T00:00:00Z",
"chunk_count": 5,
"allowed_users": [],
"allowed_groups": [],
"allowed_principal_labels": [],
}
],
"total": 1,
"is_approximate": True,
"page": 1,
"page_size": 25,
"after_key": None,
}
# ---------------------------------------------------------------------------
# list_files_public (GET /v2/files)
# ---------------------------------------------------------------------------
class TestListFilesPublic:
@pytest.mark.asyncio
async def test_returns_file_list_on_success(self):
"""Handler returns the service response as JSONResponse."""
file_service = _make_file_service(_SAMPLE_RESPONSE)
user = _make_user()
response = await list_files_public(
page=1,
page_size=25,
sort_by="filename",
sort_order="asc",
connector_type=None,
mimetype=None,
owner=None,
search=None,
after_key=None,
file_service=file_service,
user=user,
)
assert response.status_code == 200
import json
body = json.loads(response.body)
assert body["total"] == 1
assert body["files"][0]["filename"] == "report.pdf"
# Verify all filter/knowledge fields are present
f = body["files"][0]
for field in (
"document_id",
"mimetype",
"file_size",
"connector_type",
"chunk_count",
"indexed_time",
"allowed_users",
):
assert field in f, f"Missing field: {field}"
@pytest.mark.asyncio
async def test_forwards_all_params_to_service(self):
"""All query params are forwarded to FileServiceV2.list_files."""
file_service = _make_file_service(_SAMPLE_RESPONSE)
user = _make_user()
await list_files_public(
page=2,
page_size=50,
sort_by="indexed_time",
sort_order="desc",
connector_type="sharepoint",
mimetype="application/pdf",
owner="user-42",
search="report",
after_key='{"filename": "a.pdf"}',
file_service=file_service,
user=user,
)
file_service.list_files.assert_awaited_once()
call_kwargs = file_service.list_files.call_args.kwargs
assert call_kwargs["page"] == 2
assert call_kwargs["page_size"] == 50
assert call_kwargs["sort_by"] == "indexed_time"
assert call_kwargs["sort_order"] == "desc"
assert call_kwargs["connector_type"] == "sharepoint"
assert call_kwargs["mimetype"] == "application/pdf"
assert call_kwargs["owner"] == "user-42"
assert call_kwargs["search"] == "report"
assert call_kwargs["after_key"] == {"filename": "a.pdf"}
@pytest.mark.asyncio
async def test_returns_401_on_opensearch_auth_error(self):
"""OpenSearch auth errors surface as 401, not 500."""
from opensearchpy.exceptions import AuthenticationException
file_service = MagicMock()
file_service.list_files = AsyncMock(side_effect=AuthenticationException(401, "auth failed"))
user = _make_user()
response = await list_files_public(
page=1,
page_size=25,
sort_by="filename",
sort_order="asc",
connector_type=None,
mimetype=None,
owner=None,
search=None,
after_key=None,
file_service=file_service,
user=user,
)
assert response.status_code == 401
@pytest.mark.asyncio
async def test_returns_500_on_unexpected_error(self):
"""Unexpected errors return 500."""
file_service = MagicMock()
file_service.list_files = AsyncMock(side_effect=RuntimeError("boom"))
user = _make_user()
response = await list_files_public(
page=1,
page_size=25,
sort_by="filename",
sort_order="asc",
connector_type=None,
mimetype=None,
owner=None,
search=None,
after_key=None,
file_service=file_service,
user=user,
)
assert response.status_code == 500
@pytest.mark.asyncio
async def test_invalid_after_key_returns_400(self):
"""A non-JSON after_key value raises HTTPException 400 before the service is called."""
from fastapi import HTTPException
file_service = _make_file_service(_SAMPLE_RESPONSE)
user = _make_user()
with pytest.raises(HTTPException) as exc_info:
await list_files_public(
page=1,
page_size=25,
sort_by="filename",
sort_order="asc",
connector_type=None,
mimetype=None,
owner=None,
search=None,
after_key="not-valid-json",
file_service=file_service,
user=user,
)
assert exc_info.value.status_code == 400
@pytest.mark.asyncio
async def test_after_key_non_dict_returns_400(self):
"""A valid JSON non-dict after_key (e.g. a string) raises HTTPException 400."""
import json
from fastapi import HTTPException
file_service = _make_file_service(_SAMPLE_RESPONSE)
user = _make_user()
with pytest.raises(HTTPException) as exc_info:
await list_files_public(
page=1,
page_size=25,
sort_by="filename",
sort_order="asc",
connector_type=None,
mimetype=None,
owner=None,
search=None,
after_key=json.dumps("just-a-string"),
file_service=file_service,
user=user,
)
assert exc_info.value.status_code == 400
# ---------------------------------------------------------------------------
# search_files_public (GET /v2/files/search)
# ---------------------------------------------------------------------------
class TestSearchFilesPublic:
@pytest.mark.asyncio
async def test_returns_search_results_on_success(self):
"""search_files_public delegates to v2.search_files and returns its result."""
file_service = _make_file_service(_SAMPLE_RESPONSE)
user = _make_user()
response = await search_files_public(
q="report",
page=1,
page_size=25,
connector_type=None,
mimetype=None,
owner=None,
after_key=None,
file_service=file_service,
user=user,
)
assert response.status_code == 200
import json
body = json.loads(response.body)
assert "files" in body
@pytest.mark.asyncio
async def test_forwards_q_and_filters_to_service(self):
"""q and all filter params are forwarded to FileServiceV2.search_files."""
file_service = _make_file_service(_SAMPLE_RESPONSE)
user = _make_user()
await search_files_public(
q="annual report",
page=2,
page_size=10,
connector_type="gdrive",
mimetype="text/plain",
owner="user-7",
after_key=None,
file_service=file_service,
user=user,
)
file_service.search_files.assert_awaited_once()
kwargs = file_service.search_files.call_args.kwargs
assert kwargs["query"] == "annual report"
assert kwargs["connector_type"] == "gdrive"
assert kwargs["mimetype"] == "text/plain"
assert kwargs["owner"] == "user-7"