Skip to content

The agent that grows with you

21.8 KB
Raw Blame
"""Unit tests for hermes_cli.win_pty_bridge — ConPTY spawning + byte forwarding.

Windows-only counterpart to tests/hermes_cli/test_pty_bridge.py.  Drives
``WinPtyBridge`` with minimal Windows processes (``cmd.exe``, ``python -c …``)
to verify it behaves like a PTY you can read/write/resize/close, then a small
set of platform-fallback assertions (``is_available``, ``PtyUnavailableError``)
that run on every OS so the import surface stays exercised in CI.

The bridge is the ConPTY backend behind the dashboard ``/chat`` tab — see
``hermes_cli/web_server.py`` ``/api/pty`` handler — so these tests are the
unit-level half of the integration check that the dashboard chat pane is
actually live on native Windows.
"""

from __future__ import annotations

import asyncio
import logging
import os
import sys
import threading
import time
from unittest.mock import patch

import pytest

# WinPtyBridge can be imported on every platform — ``is_available`` just
# returns False when pywinpty isn't usable.  Importing the module itself
# must never raise, otherwise the web_server import branch becomes a trap.
from hermes_cli import win_pty_bridge
from hermes_cli.win_pty_bridge import PtyUnavailableError, WinPtyBridge
from tests.waiting import async_wait_until

# ``pytest.mark.platforms("windows")`` rather than a local ``skipif`` alias: the
# dedicated Windows CI job selects its files by grepping for the marker name
# and then filters with ``-m platforms("windows")``. A file-local skipif alias matched
# the grep (so the file was listed) but carried no marker, so every test below
# was deselected — the lane looked like it covered ConPTY and ran none of it.


def _read_until(bridge: WinPtyBridge, needle: bytes, timeout: float = 10.0) -> bytes:
    """Accumulate PTY output until we see ``needle`` or time out.

    Mirrors the helper in test_pty_bridge.py so failures look familiar.
    """
    deadline = time.monotonic() + timeout
    buf = bytearray()
    while time.monotonic() < deadline:
        chunk = bridge.read(timeout=0.2)
        if chunk is None:
            break
        buf.extend(chunk)
        if needle in buf:
            return bytes(buf)
    return bytes(buf)


class _HealthyProc:
    """A ConPTY whose input never wedges."""

    pid = 1

    def __init__(self):
        self.written = []
        self.terminated = threading.Event()

    def write(self, text):
        self.written.append(text)

    def terminate(self, force=False):
        self.terminated.set()


# ---------------------------------------------------------------------------
# Cross-platform fallback semantics
# ---------------------------------------------------------------------------


class TestWinPtyBridgeUnavailable:
    """Module-level surface that must stay importable on every OS so the
    web_server platform branch doesn't blow up at import time when pywinpty
    is missing or the host isn't Windows."""



    @pytest.mark.asyncio
    async def test_write_has_nonblocking_async_contract(self):
        class _FakeProc:
            pid = 1

            def __init__(self):
                self.written = []

            def write(self, text):
                self.written.append(text)

        proc = _FakeProc()
        bridge = WinPtyBridge(proc)

        assert await bridge.write(b"hello") is True
        assert proc.written == ["hello"]

    @pytest.mark.asyncio
    async def test_write_timeout_terminates_conpty_and_reaps_worker(self):
        class _BlockingProc:
            pid = 1

            def __init__(self):
                self.write_started = threading.Event()
                self.release_write = threading.Event()
                self.write_finished = threading.Event()
                self.terminated = threading.Event()

            def write(self, _text):
                self.write_started.set()
                self.release_write.wait(timeout=2.0)
                self.write_finished.set()

            def terminate(self, force=False):
                assert force is True
                self.terminated.set()
                self.release_write.set()

        proc = _BlockingProc()
        bridge = WinPtyBridge(proc)

        assert await bridge.write(b"blocked", timeout=0.01) is False
        assert proc.write_started.is_set()
        assert proc.terminated.is_set()
        assert proc.write_finished.is_set()
        assert bridge._closed is True

    @pytest.mark.asyncio
    async def test_cancelled_write_keeps_healthy_conpty_alive(self):
        """A socket dropping mid-write is not a wedged child: the PTY outlives
        its socket by design, so a write that lands within the grace window
        must not terminate the process."""
        class _SlowProc:
            pid = 1

            def __init__(self):
                self.release_write = threading.Event()
                self.terminated = threading.Event()

            def write(self, _text):
                self.release_write.wait(timeout=2.0)

            def terminate(self, force=False):
                self.terminated.set()

        proc = _SlowProc()
        bridge = WinPtyBridge(proc)
        task = asyncio.create_task(bridge.write(b"x"))
        await asyncio.sleep(0.05)
        task.cancel()
        proc.release_write.set()  # the child drains right after the socket left
        with pytest.raises(asyncio.CancelledError):
            await task
        assert not proc.terminated.is_set()
        assert bridge._closed is False

    @pytest.mark.asyncio
    async def test_cancelled_write_that_never_lands_terminates_conpty(self):
        class _WedgedProc:
            pid = 1

            def __init__(self):
                self.release_write = threading.Event()
                self.terminated = threading.Event()

            def write(self, _text):
                self.release_write.wait(timeout=5.0)

            def terminate(self, force=False):
                self.terminated.set()
                self.release_write.set()

        proc = _WedgedProc()
        bridge = WinPtyBridge(proc)
        with patch.object(win_pty_bridge, "_WRITE_SHUTDOWN_GRACE", 0.05):
            task = asyncio.create_task(bridge.write(b"x"))
            await asyncio.sleep(0.02)
            task.cancel()
            with pytest.raises(asyncio.CancelledError):
                await task
        assert proc.terminated.is_set()
        assert bridge._closed is True

    @pytest.mark.asyncio
    async def test_leaked_write_worker_is_logged(self, caplog):
        """terminate() that fails to unblock pywinpty leaves a thread parked in
        the default executor; that must be observable, not swallowed."""
        class _StuckProc:
            pid = 1

            def __init__(self):
                self.release_write = threading.Event()

            def write(self, _text):
                self.release_write.wait(timeout=5.0)

            def terminate(self, force=False):
                pass  # does NOT release the write

        proc = _StuckProc()
        bridge = WinPtyBridge(proc)
        with patch.object(win_pty_bridge, "_WRITE_SHUTDOWN_GRACE", 0.05), \
                caplog.at_level(logging.WARNING, logger="hermes_cli.win_pty_bridge"):
            assert await bridge.write(b"x", timeout=0.01) is False
        proc.release_write.set()
        assert any("thread leaked" in r.getMessage() for r in caplog.records)

    @pytest.mark.asyncio
    async def test_waiting_for_the_fence_does_not_count_against_the_write_deadline(self):
        """Other work holding the fence's profile lease is not a wedged ConPTY: a write that
        waits longer than the deadline to enter the fence still lands, and the shell survives."""
        proc = _HealthyProc()
        bridge = WinPtyBridge(proc)
        lease_free = threading.Event()
        waiting = threading.Event()

        def fence(write):
            waiting.set()
            lease_free.wait(timeout=5.0)
            return write()

        task = asyncio.create_task(bridge.write(b"keys", timeout=0.05, fence=fence))
        await async_wait_until(waiting.is_set)
        done, _ = await asyncio.wait({task}, timeout=0.3)
        assert not done
        lease_free.set()
        assert await task is True
        assert proc.written == ["keys"]
        assert not proc.terminated.is_set()

    @pytest.mark.asyncio
    async def test_a_fence_that_raises_propagates_and_keeps_conpty(self):
        """A lease that gives up is the fence refusing, not ConPTY wedging: what it raises
        reaches the caller, as on POSIX, and the shell stays up."""
        proc = _HealthyProc()
        bridge = WinPtyBridge(proc)

        def fence(_write):
            raise TimeoutError("profile lease busy")

        with pytest.raises(TimeoutError, match="profile lease busy"):
            await bridge.write(b"keys", fence=fence)
        assert proc.written == []
        assert not proc.terminated.is_set()
        assert bridge._closed is False

    @pytest.mark.asyncio
    async def test_a_write_wedged_inside_the_fence_terminates_conpty_and_frees_the_fence(self):
        """The deadline still bounds how long a wedged ConPTY can hold the fence."""
        class _WedgedProc:
            pid = 1

            def __init__(self):
                self.release_write = threading.Event()
                self.terminated = threading.Event()

            def write(self, _text):
                self.release_write.wait(timeout=5.0)

            def terminate(self, force=False):
                self.terminated.set()
                self.release_write.set()

        proc = _WedgedProc()
        bridge = WinPtyBridge(proc)
        lease = threading.Lock()

        def fence(write):
            with lease:
                return write()

        assert await bridge.write(b"x", timeout=0.05, fence=fence) is False
        assert proc.terminated.is_set()
        assert bridge._closed is True
        assert not lease.locked()

    @pytest.mark.asyncio
    async def test_a_write_cancelled_while_waiting_for_the_fence_lands_and_keeps_conpty(self):
        """A socket leaving while the lease is busy is not a stall: the keystrokes land once
        the lease frees, and the shell survives."""
        proc = _HealthyProc()
        bridge = WinPtyBridge(proc)
        lease_free = threading.Event()
        waiting = threading.Event()

        def fence(write):
            waiting.set()
            lease_free.wait(timeout=5.0)
            return write()

        with patch.object(win_pty_bridge, "_WRITE_SHUTDOWN_GRACE", 0.05):
            task = asyncio.create_task(bridge.write(b"keys", timeout=0.05, fence=fence))
            await async_wait_until(waiting.is_set)
            task.cancel()
            with pytest.raises(asyncio.CancelledError):
                await task
            assert not proc.terminated.is_set()
            lease_free.set()
            await async_wait_until(lambda: proc.written == ["keys"] and not bridge._late_writes)
        assert not proc.terminated.is_set()
        assert bridge._closed is False

    @pytest.mark.asyncio
    async def test_idle_terminals_leave_the_default_executor_free(self):
        """Every terminal's drain reads in the default executor, which also runs
        keystrokes, admission and cleanup. An idle shell's read must return on its
        timeout, or a few quiet terminals hold every worker until one prints."""
        from concurrent.futures import ThreadPoolExecutor
        import socket

        from hermes_cli.pty_session import PtySession

        class _IdleShell:
            """pywinpty 3.0.5's PtyProcess: a reader thread copies ConPTY output to a
            loopback socket, ``read`` is a blocking recv on it, ``fileno`` exposes it."""
            pid = 1

            def __init__(self):
                self.output, self.console = socket.socketpair()
                self.polled = threading.Event()

            def fileno(self):
                self.polled.set()  # the bridge's bounded select asks for it on every poll
                return self.output.fileno()

            def read(self, size):
                data = self.output.recv(size)
                if not data:
                    raise EOFError("Pty is closed")
                return data.decode("utf-8")

            def isalive(self):
                return True

            def terminate(self, force=False):
                self.console.close()

        loop = asyncio.get_running_loop()
        loop.set_default_executor(ThreadPoolExecutor(max_workers=2))
        shells = [_IdleShell() for _ in range(4)]
        sessions = [PtySession(f"terminal-{n}", WinPtyBridge(shell), buffer_cap=64, read_timeout=0.05)
                    for n, shell in enumerate(shells)]
        try:
            for session in sessions:
                await session.start()
            # Every idle shell's reader has polled it; unbounded reads on the two-worker
            # default pool would hold both workers and leave two shells never polled.
            await async_wait_until(lambda: all(shell.polled.is_set() for shell in shells), timeout=3)
            assert await asyncio.wait_for(asyncio.to_thread(lambda: "ran"), 3) == "ran"
            shells[1].console.sendall("héllo".encode())
            await async_wait_until(lambda: sessions[1].buffer.snapshot() == "héllo".encode(), timeout=3)
        finally:
            for shell in shells:
                shell.terminate()
            for session in sessions:
                await session.close()

    @pytest.mark.platforms("posix")  # non-Windows only
    def test_spawn_raises_unavailable_off_windows(self):
        with pytest.raises(PtyUnavailableError):
            WinPtyBridge.spawn(["true"])


# ---------------------------------------------------------------------------
# Windows-only end-to-end behaviour
# ---------------------------------------------------------------------------


@pytest.mark.platforms("windows")
class TestWinPtyBridgeSpawn:

    def test_spawn_returns_bridge_with_pid(self):
        bridge = WinPtyBridge.spawn(["cmd.exe", "/c", "exit 0"])
        try:
            assert bridge.pid > 0
        finally:
            bridge.close()

    def test_spawn_raises_on_missing_argv0(self, tmp_path):
        # pywinpty wraps CreateProcessW failures; surface as OSError / RuntimeError.
        bogus = str(tmp_path / "definitely-not-a-real-binary.exe")
        with pytest.raises((FileNotFoundError, OSError, RuntimeError, PtyUnavailableError)):
            WinPtyBridge.spawn([bogus])


@pytest.mark.platforms("windows")
class TestWinPtyBridgeIO:

    @pytest.mark.asyncio
    async def test_write_sends_to_child_stdin(self):
        # python -c reads stdin, echoes a marker, exits.  More reliable than
        # ``cat`` (not on Windows) and doesn't depend on a particular shell.
        script = (
            "import sys; "
            "line = sys.stdin.readline().strip(); "
            "sys.stdout.write('GOT:' + line + '\\n'); "
            "sys.stdout.flush()"
        )
        bridge = WinPtyBridge.spawn([sys.executable, "-c", script])
        try:
            assert await bridge.write(b"hello-pty\r\n") is True
            output = _read_until(bridge, b"GOT:hello-pty")
            assert b"GOT:hello-pty" in output
        finally:
            bridge.close()


    @pytest.mark.asyncio
    async def test_paste_to_a_program_that_is_not_reading_lands_at_once(self):
        """ConPTY buffers input whether or not the child reads it, so a host shell's
        paste lands at once and the job keeps running; only a wedged ConPTY can miss
        the write deadline, which is why Windows writes keep one."""
        script = "import time; time.sleep(1.5); print('SURVI' + 'VED', flush=True)"
        bridge = WinPtyBridge.spawn([sys.executable, "-c", script])
        try:
            paste = b"".join(b"%05d %s\r" % (n, b"x" * 57) for n in range(16384))  # 1 MiB
            assert await asyncio.wait_for(bridge.write(paste, timeout=None), timeout=2.0) is True
            output = await asyncio.to_thread(_read_until, bridge, b"SURVIVED", 15.0)
            assert b"SURVIVED" in output
        finally:
            bridge.close()

    def test_idle_read_returns_within_its_timeout(self):
        """A shell that prints nothing must not hold the reading thread until it
        next prints: every terminal's drain shares the default executor."""
        script = "import time; print('REA' + 'DY', flush=True); time.sleep(30)"
        bridge = WinPtyBridge.spawn([sys.executable, "-c", script])
        try:
            assert b"READY" in _read_until(bridge, b"READY")
            idle, slowest = False, 0.0
            deadline = time.monotonic() + 5.0
            while not idle and time.monotonic() < deadline:
                started = time.monotonic()
                idle = bridge.read(timeout=0.5) == b""
                slowest = max(slowest, time.monotonic() - started)
            assert idle
            assert slowest < 2.5
        finally:
            bridge.close()

    def test_read_returns_none_after_child_exits(self):
        bridge = WinPtyBridge.spawn(["cmd.exe", "/c", "echo done"])
        try:
            _read_until(bridge, b"done")
            # Give the child a beat to exit, then drain until EOF.
            deadline = time.monotonic() + 5.0
            while bridge.is_alive() and time.monotonic() < deadline:
                bridge.read(timeout=0.1)
            # ConPTY reports EOF seconds after the child exits, and read() returns b""
            # at its timeout until then, so poll to a deadline rather than a count.
            got_none = False
            deadline = time.monotonic() + 15.0
            while time.monotonic() < deadline:
                if bridge.read(timeout=0.1) is None:
                    got_none = True
                    break
            assert got_none, "WinPtyBridge.read did not return None after child EOF"
        finally:
            bridge.close()


@pytest.mark.platforms("windows")
class TestWinPtyBridgeResize:
    def test_resize_does_not_raise_on_live_child(self):
        # ConPTY exposes no ioctl-equivalent for reading the child's current
        # winsize from Python land, so we can't verify the new dimensions
        # the way the POSIX test does (which reads TIOCGWINSZ).  What we
        # CAN guarantee is what the dashboard depends on: ``resize`` never
        # raises, the bridge stays alive, and subsequent I/O still works.
        bridge = WinPtyBridge.spawn(
            [sys.executable, "-c", "import time; time.sleep(1.0)"],
            cols=80,
            rows=24,
        )
        try:
            bridge.resize(cols=123, rows=45)
            assert bridge.is_alive()
        finally:
            bridge.close()


    def test_resize_after_close_is_silent(self):
        bridge = WinPtyBridge.spawn(["cmd.exe", "/c", "exit 0"])
        bridge.close()
        # Must not raise — closed bridges still receive late resize escapes
        # from xterm.js when the browser tab is closed mid-stream.
        bridge.resize(cols=100, rows=40)


@pytest.mark.platforms("windows")
class TestClampDimension:
    """The clamp helper is the load-bearing piece — the dashboard sends
    untrusted winsize values straight from xterm.js, and pywinpty's
    setwinsize will happily raise on out-of-range u16 values."""

    def test_clamps_above_max(self):
        from hermes_cli.win_pty_bridge import _MAX_COLS, _MAX_ROWS, _clamp

        assert _clamp(131072, _MAX_COLS) == _MAX_COLS
        assert _clamp(131072, _MAX_ROWS) == _MAX_ROWS


    def test_non_numeric_falls_back_to_min(self):
        from hermes_cli.win_pty_bridge import _MAX_COLS, _clamp

        assert _clamp(None, _MAX_COLS) == 1  # type: ignore[arg-type]
        assert _clamp("not-a-number", _MAX_COLS) == 1  # type: ignore[arg-type]
        assert _clamp(float("nan"), _MAX_COLS) == 1  # type: ignore[arg-type]
        assert _clamp(float("inf"), _MAX_COLS) == 1  # type: ignore[arg-type]


@pytest.mark.platforms("windows")
class TestWinPtyBridgeClose:

    def test_close_terminates_long_running_child(self):
        bridge = WinPtyBridge.spawn(
            [sys.executable, "-c", "import time; time.sleep(30)"]
        )
        pid = bridge.pid
        assert bridge.is_alive(), f"child pid {pid} not alive before close"
        bridge.close()
        # The bridge itself reports liveness via pywinpty.isalive(), which is
        # the same probe the dashboard PTY reader uses to decide when to stop
        # forwarding bytes — verifying that flips to False is the contract
        # that matters for /api/pty.
        deadline = time.monotonic() + 5.0
        while bridge.is_alive() and time.monotonic() < deadline:
            time.sleep(0.1)
        assert not bridge.is_alive(), (
            f"WinPtyBridge.is_alive() still True after close(); pid {pid}"
        )


@pytest.mark.platforms("windows")
class TestWinPtyBridgeEnv:
    def test_cwd_is_respected(self, tmp_path):
        bridge = WinPtyBridge.spawn(
            [sys.executable, "-c", "import os; print(os.getcwd())"],
            cwd=str(tmp_path),
        )
        try:
            # Path is case-insensitive on Windows; compare lowercased.
            needle_resolved = str(tmp_path.resolve()).lower().encode()
            deadline = time.monotonic() + 5.0
            buf = bytearray()
            while time.monotonic() < deadline:
                chunk = bridge.read(timeout=0.2)
                if chunk is None:
                    break
                buf.extend(chunk)
                if needle_resolved in bytes(buf).lower():
                    break
            assert needle_resolved in bytes(buf).lower(), (
                f"cwd {tmp_path!s} not echoed by child; got {bytes(buf)!r}"
            )
        finally:
            bridge.close()

    def test_env_is_forwarded(self):
        bridge = WinPtyBridge.spawn(
            [
                sys.executable,
                "-c",
                "import os; print('HERMES_PTY_TEST=' + os.environ.get('HERMES_PTY_TEST',''))",
            ],
            env={**os.environ, "HERMES_PTY_TEST": "pty-env-works"},
        )
        try:
            output = _read_until(bridge, b"pty-env-works")
            assert b"pty-env-works" in output
        finally:
            bridge.close()