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.

5.7 KB
Raw Blame
"""Coroutine-ownership hygiene in ``socketio_asgi._schedule_coroutine_threadsafe``.

Every Socket.IO emit/disconnect from a background thread (research workers,
the log queue, the scheduler) funnels through this wrapper. It exists for
one narrow failure window: during shutdown, ``asyncio.run_coroutine_
threadsafe`` can raise SYNCHRONOUSLY (``loop.call_soon_threadsafe`` on a
closed loop) after the caller has already constructed the coroutine.

Ownership has not transferred at that point — ``run_coroutine_threadsafe``
only takes ownership once the callback is queued — so the coroutine is
orphaned with nobody left to close it. An unclosed coroutine is at
best a ``RuntimeWarning`` ("never awaited") plus a frame held until
GC. Note the coroutines this wrapper receives have never STARTED, so
any ``finally`` cleanup in their bodies was never entered — nothing
of it can "leak"; what leaks is the warning and the frame.

The scheduling-FAILURE routing around this wrapper (best-effort emits,
no-raise) is pinned in ``tests/web/services/test_socketio_asgi_scheduling_
failures.py`` by monkeypatching ``run_coroutine_threadsafe``, and that file
already pins — six times, via its ``_assert_one_closed_coroutine`` helper —
that a synchronously rejected coroutine is CLOSED. What that file does NOT
pin, because it only exercises the emit/disconnect wrappers' best-effort,
no-raise contract, is the ownership contract of this wrapper itself, at the
seam where the exception is still live:

1. the ORIGINAL exception type propagates unwrapped OUT of
   ``_schedule_coroutine_threadsafe``, so a direct caller sees e.g.
   ``RuntimeError`` rather than a generic wrapper error — the higher-level
   wrappers in the other file catch and swallow this before it can
   surface, so it is untested there; and
2. on the SUCCESS path the coroutine is NOT closed — ownership has
   transferred to the loop, and closing it here would surface as a
   spurious shutdown error once the loop tries to drive it. The other
   file never exercises the success path at all.
"""

import asyncio

import pytest

from local_deep_research.web.services.socketio_asgi import (
    _schedule_coroutine_threadsafe,
)


def _pending_coroutine():
    # A coroutine in the state the wrapper actually receives: created,
    # never started. (``close()`` on a never-started coroutine does NOT
    # run its body — the try/finally was never entered — so "finally
    # ran" cannot be the observable. The leak being prevented is the
    # "coroutine ... was never awaited" GC report; ``cr_frame is None``
    # below is what closing actually looks like from the outside.)
    async def coro():
        await asyncio.sleep(3600)

    return coro()


class TestSynchronousRejection:
    def test_rejected_coroutine_is_closed(self, monkeypatch):
        scheduled = []

        def rejecting(coro, loop):
            scheduled.append((coro, loop))
            raise RuntimeError("loop is closed")

        monkeypatch.setattr(asyncio, "run_coroutine_threadsafe", rejecting)

        coro = _pending_coroutine()
        loop = object()  # identity sentinel: no real loop is needed here
        with pytest.raises(RuntimeError, match="loop is closed"):
            _schedule_coroutine_threadsafe(coro, loop)

        # The caller's loop must be the one handed to the scheduler —
        # falling back to a global/ambient loop would schedule background
        # emits onto the wrong loop, which is exactly the shutdown-race
        # bug this wrapper sits in the middle of.
        assert scheduled == [(coro, loop)]
        # Closed == frame released; without the close, GC would later
        # emit "coroutine ... was never awaited" — the exact warning
        # this wrapper exists to prevent during shutdown races. (A
        # gc.collect()-and-assert-no-warning block used to follow this
        # assertion; it is documentation, not a guard — once cr_frame is
        # None the coroutine is already closed, so that warning can never
        # fire independently of the assertion above failing first.)
        assert coro.cr_frame is None

    def test_original_exception_type_propagates_unwrapped(self, monkeypatch):
        class ShutdownRace(Exception):
            """Distinctive type: proves no re-wrapping occurs."""

        def rejecting(coro, loop):
            raise ShutdownRace

        monkeypatch.setattr(asyncio, "run_coroutine_threadsafe", rejecting)

        with pytest.raises(ShutdownRace):
            _schedule_coroutine_threadsafe(_pending_coroutine(), object())

    def test_success_path_does_not_close_the_coroutine(self, monkeypatch):
        # Ownership mirror-image: once scheduling is ACCEPTED, the
        # coroutine belongs to the event loop. The wrapper must not
        # close it (closing a coroutine the loop will drive would
        # surface as spurious shutdown errors).
        scheduled = []

        def accepting(coro, loop):
            scheduled.append((coro, loop))
            return object()  # caller-discarded future stand-in

        monkeypatch.setattr(asyncio, "run_coroutine_threadsafe", accepting)

        coro = _pending_coroutine()
        loop = object()
        _schedule_coroutine_threadsafe(coro, loop)

        # Both operands, in order: the caller's coroutine AND the caller's
        # loop reach the scheduler unchanged.
        assert scheduled == [(coro, loop)]
        assert coro.cr_frame is not None  # still open: owned by the loop
        # Clean up what the stand-in future never will. (A close() +
        # gc.collect() + assert-no-warning block used to follow here; it
        # is documentation, not a guard — it only pins CPython's own
        # coroutine-close semantics on cleanup code this test wrote
        # itself, not anything the wrapper under test does.)
        coro.close()