Skip to content

DeepTutor: Lifelong Personalized Tutoring. https://deeptutor.info/.

14.5 KB
Raw Blame
"""Contract tests for the KB upload/delete route guards.

``deeptutor/api/routers/knowledge.py`` is the data-integrity entry point for
knowledge bases; the happy paths were covered but the guard rails were not.
Three contracts are locked here, matching the coverage-gap evidence card:

1. a rejected upload batch fails with 4xx and leaves nothing behind — no
   staged files under ``raw/``, no queued task, no status flip;
2. task IDs are idempotent per logical task key (a retried dispatch reuses
   its ID) while two accepted uploads never share one;
3. deleting a raw document (or a whole KB) keeps the file listing, the
   indexed-hash metadata and the disk consistent.

No product code is changed by this file.
"""

from __future__ import annotations

import importlib
import io
import json
from pathlib import Path

import pytest

pytest.importorskip("fastapi")
from fastapi import FastAPI, UploadFile
from fastapi.testclient import TestClient

from deeptutor.api.utils.task_id_manager import TaskIDManager
from deeptutor.utils.document_validator import DocumentValidator

try:
    knowledge_router_module = importlib.import_module("deeptutor.api.routers.knowledge")
    router = knowledge_router_module.router
except Exception:  # pragma: no cover - optional heavy imports in lightweight envs
    knowledge_router_module = None
    router = None

pytestmark = pytest.mark.skipif(
    router is None, reason="deeptutor.api.routers.knowledge could not be imported"
)


@pytest.fixture(autouse=True)
def _disable_pocketbase(monkeypatch):
    monkeypatch.setattr("deeptutor.services.pocketbase_client.is_pocketbase_enabled", lambda: False)


def _build_app() -> FastAPI:
    app = FastAPI()
    app.include_router(router, prefix="/api")
    return app


def _real_manager(monkeypatch, tmp_path: Path):
    """A real ``KnowledgeBaseManager`` on a throwaway base dir.

    The delete/listing contracts below are about actual disk and config
    consistency, so the real manager is used instead of a fake.
    """
    from deeptutor.knowledge.manager import KnowledgeBaseManager

    manager = KnowledgeBaseManager(base_dir=str(tmp_path / "kbs"))
    monkeypatch.setattr(knowledge_router_module, "get_kb_manager", lambda: manager)
    return manager


def _seed_kb(
    manager,
    name: str = "kb",
    *,
    files: dict[str, str] | None = None,
    file_hashes: dict[str, str] | None = None,
) -> Path:
    """Create a ready llamaindex KB with raw files and indexed hashes."""
    kb_dir = manager.base_dir / name
    raw_dir = kb_dir / "raw"
    raw_dir.mkdir(parents=True, exist_ok=True)
    for rel_name, content in (files or {}).items():
        target = raw_dir / rel_name
        target.parent.mkdir(parents=True, exist_ok=True)
        target.write_text(content, encoding="utf-8")

    manager.config.setdefault("knowledge_bases", {})[name] = {
        "path": name,
        "rag_provider": "llamaindex",
        "status": "ready",
    }
    manager._save_config()

    metadata: dict = {"rag_provider": "llamaindex", "needs_reindex": False}
    if file_hashes is not None:
        metadata["file_hashes"] = dict(file_hashes)
    (kb_dir / "metadata.json").write_text(json.dumps(metadata), encoding="utf-8")
    return kb_dir


def _upload(filename: str, payload: bytes) -> list[tuple[str, tuple[str, bytes, str]]]:
    return [("files", (filename, payload, "application/octet-stream"))]


def _staged_files(raw_dir: Path) -> list[Path]:
    """Files left under ``raw/`` after a request (empty raw dir is fine)."""
    if not raw_dir.exists():
        return []
    return [path for path in raw_dir.rglob("*") if path.is_file()]


class _DispatchRecorder:
    def __init__(self) -> None:
        self.calls: list[dict] = []

    async def __call__(self, *args, **kwargs):
        self.calls.append(kwargs)
        return None


def _install_dispatch_recorder(monkeypatch) -> _DispatchRecorder:
    recorder = _DispatchRecorder()
    monkeypatch.setattr(knowledge_router_module, "run_upload_processing_task", recorder)
    return recorder


# ---------------------------------------------------------------------------
# 1. Rejected upload batches leave nothing behind
# ---------------------------------------------------------------------------


def test_upload_rejects_unsupported_extension_without_side_effects(
    monkeypatch, tmp_path: Path
) -> None:
    manager = _real_manager(monkeypatch, tmp_path)
    _seed_kb(manager, files={})
    recorder = _install_dispatch_recorder(monkeypatch)

    with TestClient(_build_app()) as client:
        response = client.post(
            "/api/knowledge-bases/kb/upload",
            files=_upload("payload.unsupported", b"binary"),
        )

    assert response.status_code == 400
    assert "unsupported file type" in response.json()["detail"].lower()
    # Nothing staged on disk, no task dispatched, no status flip.
    assert _staged_files(manager.base_dir / "kb" / "raw") == []
    assert recorder.calls == []
    entry = json.loads((manager.base_dir / "kb_config.json").read_text(encoding="utf-8"))[
        "knowledge_bases"
    ]["kb"]
    assert entry["status"] == "ready"
    assert not entry.get("progress")


def test_upload_rejects_oversize_file_without_side_effects(monkeypatch, tmp_path: Path) -> None:
    manager = _real_manager(monkeypatch, tmp_path)
    _seed_kb(manager, files={})
    recorder = _install_dispatch_recorder(monkeypatch)
    monkeypatch.setattr(DocumentValidator, "MAX_FILE_SIZE", 32)

    with TestClient(_build_app()) as client:
        response = client.post(
            "/api/knowledge-bases/kb/upload", files=_upload("big.txt", b"x" * 100)
        )

    assert response.status_code == 400
    assert "too large" in response.json()["detail"].lower()
    assert _staged_files(manager.base_dir / "kb" / "raw") == []
    assert recorder.calls == []
    entry = json.loads((manager.base_dir / "kb_config.json").read_text(encoding="utf-8"))[
        "knowledge_bases"
    ]["kb"]
    assert entry["status"] == "ready"


def test_upload_rejects_duplicate_names_within_one_batch(monkeypatch, tmp_path: Path) -> None:
    manager = _real_manager(monkeypatch, tmp_path)
    _seed_kb(manager, files={})
    recorder = _install_dispatch_recorder(monkeypatch)

    with TestClient(_build_app()) as client:
        response = client.post(
            "/api/knowledge-bases/kb/upload",
            files=[*_upload("notes.txt", b"one"), *_upload("notes.txt", b"two")],
        )

    assert response.status_code == 400
    assert "duplicate filename" in response.json()["detail"].lower()
    assert _staged_files(manager.base_dir / "kb" / "raw") == []
    assert recorder.calls == []


def test_upload_rejects_provider_mismatch_with_kb(monkeypatch, tmp_path: Path) -> None:
    manager = _real_manager(monkeypatch, tmp_path)
    _seed_kb(manager, files={})
    recorder = _install_dispatch_recorder(monkeypatch)

    with TestClient(_build_app()) as client:
        response = client.post(
            "/api/knowledge-bases/kb/upload",
            data={"rag_provider": "pageindex"},
            files=_upload("demo.txt", b"hello"),
        )

    assert response.status_code == 400
    assert "does not match kb provider" in response.json()["detail"].lower()
    assert recorder.calls == []


def test_rejected_batch_member_rolls_back_earlier_writes(tmp_path: Path) -> None:
    """A failure on any member unlinks the files already written (unit level).

    The route-level batch pre-validation catches most of these earlier; this
    exercises the rollback inside ``_save_uploaded_files`` itself.
    """
    raw = tmp_path / "raw"
    raw.mkdir()
    batch = [
        UploadFile(filename="ok.txt", file=io.BytesIO(b"hello")),
        UploadFile(filename="bad.exe", file=io.BytesIO(b"binary")),
    ]

    with pytest.raises(knowledge_router_module.HTTPException) as exc_info:
        knowledge_router_module._save_uploaded_files(batch, raw, allowed_extensions={".txt"})

    assert exc_info.value.status_code == 400
    assert not any(raw.rglob("*"))  # ok.txt was written, then rolled back


def test_mid_write_size_limit_removes_the_partial_file(monkeypatch, tmp_path: Path) -> None:
    """A stream whose size cannot be probed is bounded while it is written."""

    class _SizeOpaqueStream(io.BytesIO):
        def tell(self):  # size probe fails -> validation skips the size check
            raise OSError("position unavailable")

    monkeypatch.setattr(DocumentValidator, "MAX_FILE_SIZE", 16)
    raw = tmp_path / "raw"
    raw.mkdir()
    upload = UploadFile(filename="huge.txt", file=_SizeOpaqueStream(b"x" * 100))

    with pytest.raises(knowledge_router_module.HTTPException) as exc_info:
        knowledge_router_module._save_uploaded_files([upload], raw, allowed_extensions={".txt"})

    assert exc_info.value.status_code == 400
    assert "exceeds maximum size" in exc_info.value.detail.lower()
    assert not any(raw.rglob("*"))  # the partial file was unlinked, not staged


# ---------------------------------------------------------------------------
# 2. Task ID idempotency
# ---------------------------------------------------------------------------


def _fresh_task_manager():
    manager = TaskIDManager()
    manager._task_ids = {}
    manager._task_metadata = {}
    return manager


def test_duplicate_task_key_maps_to_the_same_task_id() -> None:
    manager = _fresh_task_manager()

    first = manager.generate_task_id("kb_upload", "kb-upload-key")
    second = manager.generate_task_id("kb_upload", "kb-upload-key")

    assert first == second  # a retried dispatch reuses its task
    assert list(manager._task_metadata) == [first]
    assert manager.get_task_metadata(first)["status"] == "running"

    other = manager.generate_task_id("kb_upload", "kb-upload-other")
    assert other != first


def test_build_unique_task_id_never_collides_for_distinct_uploads(
    monkeypatch,
) -> None:
    fresh = _fresh_task_manager()
    monkeypatch.setattr(TaskIDManager, "get_instance", classmethod(lambda cls: fresh))

    first = knowledge_router_module._build_unique_task_id("kb_upload", "kb-a")
    second = knowledge_router_module._build_unique_task_id("kb_upload", "kb-a")

    assert first != second  # two accepted uploads never share a task
    assert first.startswith("kb_upload_") and second.startswith("kb_upload_")
    assert set(fresh._task_metadata) == {first, second}


def test_two_uploads_dispatch_two_distinct_tasks(monkeypatch, tmp_path: Path) -> None:
    manager = _real_manager(monkeypatch, tmp_path)
    _seed_kb(manager, files={})
    recorder = _install_dispatch_recorder(monkeypatch)
    fresh = _fresh_task_manager()
    monkeypatch.setattr(TaskIDManager, "get_instance", classmethod(lambda cls: fresh))

    with TestClient(_build_app()) as client:
        first = client.post("/api/knowledge-bases/kb/upload", files=_upload("one.txt", b"one"))
        second = client.post("/api/knowledge-bases/kb/upload", files=_upload("two.txt", b"two"))

    assert first.status_code == 200
    assert second.status_code == 200
    first_task = first.json()["task_id"]
    second_task = second.json()["task_id"]
    assert first_task != second_task
    assert first_task.startswith("kb_upload_")

    # Both uploads queued exactly one background task, each with its own ID.
    assert len(recorder.calls) == 2
    assert {call["task_id"] for call in recorder.calls} == {first_task, second_task}

    # The queued status points at the task that was actually dispatched.
    entry = json.loads((manager.base_dir / "kb_config.json").read_text(encoding="utf-8"))[
        "knowledge_bases"
    ]["kb"]
    assert entry["status"] == "processing"
    assert entry["progress"]["task_id"] == second_task


# ---------------------------------------------------------------------------
# 3. Delete keeps listing, metadata and disk consistent
# ---------------------------------------------------------------------------


def test_delete_raw_file_updates_listing_metadata_and_disk(monkeypatch, tmp_path: Path) -> None:
    manager = _real_manager(monkeypatch, tmp_path)
    kb_dir = _seed_kb(
        manager,
        files={"notes.txt": "hello", "docs/paper.md": "# paper"},
        file_hashes={"notes.txt": "h-notes", "docs/paper.md": "h-paper"},
    )

    with TestClient(_build_app()) as client:
        listing_before = client.get("/api/knowledge-bases/kb/files").json()["files"]
        removal = client.delete("/api/knowledge-bases/kb/files/notes.txt")
        listing_after = client.get("/api/knowledge-bases/kb/files").json()["files"]
        repeat = client.delete("/api/knowledge-bases/kb/files/notes.txt")

    assert {entry["name"] for entry in listing_before} == {
        "notes.txt",
        "docs",
        "docs/paper.md",
    }
    assert removal.status_code == 200
    assert removal.json() == {"status": "ok", "path": "notes.txt", "was_indexed": True}

    # Listing no longer shows the file…
    assert {entry["name"] for entry in listing_after} == {"docs", "docs/paper.md"}
    # …the disk copy is gone while siblings survive…
    assert not (kb_dir / "raw" / "notes.txt").exists()
    assert (kb_dir / "raw" / "docs" / "paper.md").read_text(encoding="utf-8") == "# paper"
    # …and the indexed-hash record was dropped with it.
    metadata = json.loads((kb_dir / "metadata.json").read_text(encoding="utf-8"))
    assert metadata["file_hashes"] == {"docs/paper.md": "h-paper"}

    assert repeat.status_code == 404
    assert repeat.json()["detail"] == "File not found"


def test_delete_whole_kb_updates_listing_and_disk(monkeypatch, tmp_path: Path) -> None:
    manager = _real_manager(monkeypatch, tmp_path)
    kb_dir = _seed_kb(manager, files={"notes.txt": "hello"})
    second_dir = _seed_kb(manager, "kb-two", files={"extra.md": "x"})

    with TestClient(_build_app()) as client:
        names_before = {item["name"] for item in client.get("/api/knowledge-bases").json()}
        path_route = client.delete("/api/knowledge-bases/kb")
        repeat = client.delete("/api/knowledge-bases/kb")
        body_route = client.post("/api/knowledge-bases/delete", json={"name": "kb-two"})
        listing = client.get("/api/knowledge-bases").json()

    assert names_before == {"kb", "kb-two"}
    assert path_route.status_code == 200
    assert path_route.json()["message"] == "Knowledge base 'kb' deleted successfully"
    assert repeat.status_code == 404
    assert body_route.status_code == 200
    assert body_route.json()["message"] == "Knowledge base 'kb-two' deleted successfully"

    # Both the config listing and the directories on disk are empty afterwards.
    assert listing == []
    assert not kb_dir.exists()
    assert not second_dir.exists()
    assert (
        json.loads((manager.base_dir / "kb_config.json").read_text(encoding="utf-8"))[
            "knowledge_bases"
        ]
        == {}
    )