Skip to content

~95% on SimpleQA (e.g. Qwen3.6-27B on a 3090). Supports all local and cloud LLMs (llama.cpp, Ollama, Google, ...). 10+ search engines - arXiv, PubMed, your private documents. Everything Local & Encrypted.

6.8 KB
Raw Blame
"""Contract tests for the ``arxiv_api_request_gate`` policy utility.

Issue #4783: every ``export.arxiv.org`` API request must traverse one
process-wide monotonic 3-second single-flight gate.

The utility ``local_deep_research.utilities.arxiv_api`` is the sole policy
owner and must expose ``arxiv_api_request_gate()`` as a context manager:
entering marks a spaced start under the process-wide lock (single-flight,
at least three monotonic seconds between starts, failed starts still count
for spacing, lock always released).

Deterministic seams mirror the downloader gate naming so existing test
patches retarget cleanly: ``_arxiv_api_request_lock``,
``_last_request_started_at``, ``_monotonic``, ``_sleep``.
"""

import threading
import types
from collections.abc import Iterator

import pytest
from pytest_mock import MockerFixture

from local_deep_research.utilities import arxiv_api as arxiv_api_module


@pytest.fixture(autouse=True)
def fresh_arxiv_api_gate() -> Iterator[None]:
    """Reset the process-wide gate state around each test."""
    with arxiv_api_module._arxiv_api_request_lock:
        arxiv_api_module._last_request_started_at = None
    yield
    with arxiv_api_module._arxiv_api_request_lock:
        arxiv_api_module._last_request_started_at = None


class TestArxivApiRequestGate:
    """Tests for the ``arxiv_api_request_gate`` context manager."""

    def test_first_gated_start_begins_immediately(
        self, mocker: MockerFixture
    ) -> None:
        # Given a fresh process gate and a deterministic monotonic clock
        starts: list[float] = []
        mocker.patch.object(arxiv_api_module, "_monotonic", return_value=10.0)
        hard_sleep = mocker.patch.object(arxiv_api_module, "_sleep")

        # When the first gated request starts
        with arxiv_api_module.arxiv_api_request_gate():
            starts.append(arxiv_api_module._monotonic())

        # Then the policy gate starts it immediately
        assert starts == [10.0]
        hard_sleep.assert_not_called()

    def test_starts_are_spaced_process_wide(
        self, mocker: MockerFixture
    ) -> None:
        # Given a clock advanced only by policy sleep
        now = 100.0
        starts: list[float] = []
        sleeps: list[float] = []

        def monotonic() -> float:
            return now

        def sleep(duration: float) -> None:
            nonlocal now
            sleeps.append(duration)
            now += duration

        mocker.patch.object(
            arxiv_api_module, "_monotonic", side_effect=monotonic
        )
        mocker.patch.object(arxiv_api_module, "_sleep", side_effect=sleep)

        # When two independent gated requests start
        with arxiv_api_module.arxiv_api_request_gate():
            starts.append(now)
        with arxiv_api_module.arxiv_api_request_gate():
            starts.append(now)

        # Then their starts are at least three seconds apart
        assert starts == [100.0, 103.0]
        assert sleeps == [3.0]

    def test_concurrent_gated_starts_are_single_flight(
        self, mocker: MockerFixture
    ) -> None:
        # Given two gated bodies that would overlap without the gate lock
        now = 200.0
        active_requests = 0
        maximum_active_requests = 0
        call_count = 0
        activity_lock = threading.Lock()
        first_request_entered = threading.Event()
        second_request_waiting_for_gate = threading.Event()

        gate_lock = threading.Lock()

        class ObservedLock:
            def __enter__(self) -> "ObservedLock":
                if gate_lock.locked():
                    second_request_waiting_for_gate.set()
                gate_lock.acquire()
                return self

            def __exit__(
                self,
                _exc_type: type[BaseException] | None,
                _exc_val: BaseException | None,
                _exc_tb: types.TracebackType | None,
            ) -> None:
                gate_lock.release()

        def monotonic() -> float:
            return now

        def sleep(duration: float) -> None:
            nonlocal now
            now += duration

        def gated_body() -> None:
            nonlocal active_requests, call_count, maximum_active_requests
            with arxiv_api_module.arxiv_api_request_gate():
                with activity_lock:
                    call_count += 1
                    request_number = call_count
                    active_requests += 1
                    maximum_active_requests = max(
                        maximum_active_requests, active_requests
                    )
                try:
                    if request_number == 1:
                        first_request_entered.set()
                        assert second_request_waiting_for_gate.wait(timeout=1)
                finally:
                    with activity_lock:
                        active_requests -= 1

        mocker.patch.object(
            arxiv_api_module, "_arxiv_api_request_lock", ObservedLock()
        )
        mocker.patch.object(
            arxiv_api_module, "_monotonic", side_effect=monotonic
        )
        mocker.patch.object(arxiv_api_module, "_sleep", side_effect=sleep)

        first_thread = threading.Thread(target=gated_body)
        second_thread = threading.Thread(target=gated_body)

        # When both gated requests run concurrently
        first_thread.start()
        assert first_request_entered.wait(timeout=1)
        second_thread.start()
        first_thread.join(timeout=1)
        second_thread.join(timeout=1)

        # Then only one gated body is active at a time
        assert not first_thread.is_alive()
        assert not second_thread.is_alive()
        assert second_request_waiting_for_gate.is_set()
        assert maximum_active_requests == 1

    def test_failed_start_still_counts_for_spacing(
        self, mocker: MockerFixture
    ) -> None:
        # Given a gated start whose body raises and a deterministic clock
        now = 400.0
        starts: list[float] = []
        sleeps: list[float] = []

        def monotonic() -> float:
            return now

        def sleep(duration: float) -> None:
            nonlocal now
            sleeps.append(duration)
            now += duration

        mocker.patch.object(
            arxiv_api_module, "_monotonic", side_effect=monotonic
        )
        mocker.patch.object(arxiv_api_module, "_sleep", side_effect=sleep)

        # When the failed start is followed by another gated request
        with pytest.raises(ConnectionError):
            with arxiv_api_module.arxiv_api_request_gate():
                starts.append(now)
                raise ConnectionError("connection refused")

        with arxiv_api_module.arxiv_api_request_gate():
            starts.append(now)

        # Then the lock is released but the failed start still counts
        assert starts == [400.0, 403.0]
        assert sleeps == [3.0]