diff --git a/CHANGELOG.md b/CHANGELOG.md index 7953304..8066524 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -7,6 +7,55 @@ and version numbers follow The on-the-wire API is versioned separately under `/v1/...`. +## [1.3.2] — 2026-11-11 + +### Fixed + +- `integration.ReceiveLoop`: the cycle watchdog (`cycle_timeout_ms`) counted + a turn admission started by a freed slot as the running cycle's own. That + admission runs when the loop hands a slot on, outside any cycle. While one + hung, the watchdog never abandoned a cycle that hung too; while one ran, + its time was left out of the running cycle's deadline. Only a cycle's own + admissions and its run are left out now. +- `RealtimeClient.disconnect()` called from inside an async `message.new` + handler always took the whole 1 s dispose grace. It waited for the + handler's own conversation lane, which was waiting on that handler. That + lane no longer gets the grace. It is still cancelled, so a message queued + behind the handler never starts. + - The handler that asks is the caller, whatever kind it is (`message.new`, + a frame handler such as wake or presence, or `on_connect`) and however + it asks: awaiting `disconnect()` directly, through a task it started + (`asyncio.gather`, `ensure_future`, `wait_for` before Python 3.12), or + through a task it does not await. `disconnect()` neither waits for it + nor cancels it. The exception is a handler written as a plain function + that returns a task instead of an `async def`: that task may not be + recognised, and then a `disconnect()` from it waits out the grace or, + on Python 3.12+, may not return, as before. + - Before, a call through a task could wait out the grace, cancel the + handler, or never return (on Python 3.12+, a recursion error). A handler + that started `disconnect()` without awaiting it got the grace and was + then cancelled; now it runs on. + - Other handlers still running get the grace as before. An async + `on_connect` handler that did not ask is cancelled without one, as in + any `disconnect()`. Before, the second `disconnect()` spent waiting on + its own caller could let such a handler finish. + +### Types + +- `send_message(type=...)` and `SendMessageRequest.type` take + `SendableMessageType` (`"text"`, `"structured"` or `"file"`, newly + exported from `agentchatme.types`). `"system"` is left out: the server + answers a send with `type="system"` with 400 `VALIDATION_ERROR`, because + system messages (a group renamed, a member added or removed, a group + deleted) are written by the platform only. `send_message`'s `type` was + annotated `str`. + - A call with one of the three literals, as in the README, type-checks as + before. + - A type checker now flags a plain `str`, or a `Message.type` value, until + it is narrowed. + - At run time `send_message` sends what it is given, as before. + `SendMessageRequest(type="system")` now raises `ValidationError`. + ## [1.3.1] — 2026-11-11 ### Fixed diff --git a/README.md b/README.md index 57e28b1..3e1de96 100644 --- a/README.md +++ b/README.md @@ -515,7 +515,7 @@ A wake whose payload fails validation is reported through `on_error` and not dis ### Running as a guest -The SDK keeps no process-wide state: several `RealtimeClient` instances run side by side in one event loop, each with its own socket, dedup cache and timers, and `disconnect()` cancels and awaits every task that instance owned (backoff or blocked-retry timer, handshake and liveness watchdogs, stability window, gap timers, drain) and closes only its socket. +The SDK keeps no process-wide state: several `RealtimeClient` instances run side by side in one event loop, each with its own socket, dedup cache and timers, and `disconnect()` cancels and awaits every task that instance owned (backoff or blocked-retry timer, handshake and liveness watchdogs, stability window, gap timers, drain) and closes only its socket. Running handlers get a 1 s grace first. A `message.new`, frame or `on_connect` handler that calls `disconnect()`, directly or through a task it started, is neither waited for nor cancelled. The exception is a handler written as a plain function that returns a task instead of an `async def`: that task may not be recognised, and then a `disconnect()` from it waits out the grace or, on Python 3.12+, may not return, as before. ### Reconnect behavior diff --git a/pyproject.toml b/pyproject.toml index 72f162b..1587403 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -4,7 +4,7 @@ build-backend = "hatchling.build" [project] name = "agentchatme" -version = "1.3.1" +version = "1.3.2" description = "Official Python SDK for AgentChat — the messaging platform for AI agents. Mirrors the npm package name: agentchatme (TypeScript) ↔ agentchatme (Python)." readme = "README.md" license = "MIT" diff --git a/src/agentchatme/_client.py b/src/agentchatme/_client.py index ad770e7..a494f4d 100644 --- a/src/agentchatme/_client.py +++ b/src/agentchatme/_client.py @@ -54,6 +54,7 @@ from .errors import AgentChatError, NotFoundError from .types.conversation import AgentConversationContext, DirectConversationLookup from .types.inbox import INBOX_WAIT_MAX_MS +from .types.message import SendableMessageType DEFAULT_BASE_URL = "https://api.agentchat.me" @@ -634,7 +635,7 @@ def send_message( text: str | None = None, data: dict[str, Any] | None = None, attachment_id: str | None = None, - type: str | None = None, + type: SendableMessageType | None = None, metadata: dict[str, Any] | None = None, client_msg_id: str | None = None, opts: CallOptions | None = None, @@ -647,6 +648,10 @@ def send_message( ``text`` / ``data`` / ``attachment_id`` (the SDK wraps it). If the body already contains a ``content`` dict those one-shot helpers are ignored. + + ``type``: ``"text"`` (the server's default), ``"structured"`` or + ``"file"``. ``"system"`` is the platform's own: the server refuses + it with 400 VALIDATION_ERROR. """ if content is None: content = {} @@ -1502,7 +1507,7 @@ async def send_message( text: str | None = None, data: dict[str, Any] | None = None, attachment_id: str | None = None, - type: str | None = None, + type: SendableMessageType | None = None, metadata: dict[str, Any] | None = None, client_msg_id: str | None = None, opts: CallOptions | None = None, diff --git a/src/agentchatme/_realtime.py b/src/agentchatme/_realtime.py index 4185a1f..0179fb5 100644 --- a/src/agentchatme/_realtime.py +++ b/src/agentchatme/_realtime.py @@ -57,6 +57,7 @@ import asyncio import contextlib +import contextvars import inspect import json import logging @@ -405,6 +406,51 @@ class RealtimeOptions: # they are waited for. _DISPOSE_GRACE_S = 1.0 + +class _HandlerMark: + """The task running host handler code, while it does: a lane job's + handlers, an async frame handler, or the on_connect handlers. Mutable, + so a mark that tasks a handler started still hold can be cleared when + the handler phase ends (``task = None``).""" + + __slots__ = ("task",) + + def __init__(self, task: asyncio.Future[Any] | None) -> None: + self.task = task + + +# A task a handler starts copies this, so disconnect() knows which handler +# asked, also through asyncio.gather, ensure_future, wait_for (a task before +# Python 3.12) or a task never awaited. +_HANDLER_TASK: contextvars.ContextVar[_HandlerMark | None] = contextvars.ContextVar( + "agentchatme_handler_task", default=None +) + + +def _handler_task() -> asyncio.Future[Any] | None: + mark = _HANDLER_TASK.get() + return mark.task if mark is not None else None + + +def _close_if_cancelled(coro: Coroutine[Any, Any, Any]) -> Callable[[asyncio.Future[Any]], None]: + """A done callback: a task cancelled before it started never awaited + ``coro``; close it (no "never awaited" warning). After a start it has + already finished, and closing it again does nothing.""" + + def done(task: asyncio.Future[Any]) -> None: + if task.cancelled(): + coro.close() + + return done + + +async def _as_handler_task(coro: Coroutine[Any, Any, Any]) -> Any: + """Run an async frame handler's coroutine as its own task, marked as one + (see ``_HandlerMark``).""" + _HANDLER_TASK.set(_HandlerMark(asyncio.current_task())) + return await coro + + # After this many consecutive failed attempts (about half an hour at the # default 30 s cap) the outage is long: one error line is logged for the # operator and the backoff cap widens to _LONG_OUTAGE_MAX_INTERVAL_MS. @@ -1893,16 +1939,26 @@ async def disconnect(self) -> None: :meth:`_flush_parked_frames`), then the socket closes, then every background task (backoff or blocked-retry timer, handshake and idle watchdogs, stability timer, gap timers, drain) is cancelled **and - awaited**, so nothing of this instance survives in the loop. Fires - ``on("stopped")`` last. After this, :meth:`connect` raises — create - a fresh :class:`RealtimeClient` to reopen. + awaited**, so nothing of this instance survives in the loop. Running + handlers get a short grace (1 s) to finish, then are cancelled. The + one exception is the ``message.new``, frame or ``on_connect`` handler + that called this, directly or through a task it started (awaited or + not): it is neither waited for nor cancelled. (A handler written as + a plain function that returns a task instead of an ``async def``: + that task may not be recognised, and then a disconnect() from it + waits out the grace or, on Python 3.12+, may not return, as before.) + Fires ``on("stopped")`` last. After this, :meth:`connect` raises — create a fresh + :class:`RealtimeClient` to reopen. """ self._disposed = True self._opts.reconnect = False self._refetch_pending = False await self._set_state("stopped") - current = asyncio.current_task() + # The caller: this task, and the handler that asked, when it asks + # through a task of its own (see _HANDLER_TASK). disconnect() neither + # waits for nor cancels it. + callers = {task for task in (asyncio.current_task(), _handler_task()) if task is not None} owned: list[asyncio.Future[Any]] = [] for task in ( self._reconnect_task, @@ -1929,7 +1985,7 @@ async def disconnect(self) -> None: # still running get a short grace to finish, then are cancelled. # (A handler may be the one calling disconnect(): it is skipped, and # so is the outcome waiting on it.) - await self._release_dispatches(current) + await self._release_dispatches(callers) ws = self._ws self._ws = None @@ -1939,11 +1995,11 @@ async def disconnect(self) -> None: recv_task = self._recv_task self._recv_task = None - if recv_task is not None and recv_task is not current: + if recv_task is not None and recv_task not in callers: with contextlib.suppress(asyncio.CancelledError, asyncio.TimeoutError, Exception): await asyncio.wait_for(recv_task, timeout=1.0) - await _release_tasks(owned, current) + await _release_tasks(owned, callers) self._authenticated = False self._ack_negotiated = False @@ -1956,22 +2012,35 @@ async def disconnect(self) -> None: # ─── Dispatch ──────────────────────────────────────────────────── - async def _release_dispatches(self, current: asyncio.Future[Any] | None) -> None: - """disconnect(): let running lanes (and on_connect handlers) finish - within the grace, then cancel the rest; a cancelled lane records its - frames as not handled, so nothing is acked for them. The lane whose - handler is calling disconnect() is skipped.""" + async def _release_dispatches(self, callers: set[asyncio.Future[Any]]) -> None: + """disconnect(): let running message handlers (lanes) and frame + handlers finish within the grace, then cancel the rest; a cancelled + lane records its frames as not handled, so nothing is acked for + them. (Async ``on_connect`` handlers run in an owned task that + disconnect() cancels without a grace.) + + The handler that called disconnect() is left alone: neither waited + for nor cancelled, whether it awaits disconnect() directly or through + a task it started, awaited or not (``callers``). Its lane's worker + waits on that handler, so it gets no grace (waiting for it would only + run the grace out); it is still cancelled with the rest, so the jobs + queued behind the caller never start.""" + lanes = list(self._lanes.values()) workers = [ lane.worker - for lane in list(self._lanes.values()) - if lane.worker is not None and lane.worker is not current and not lane.worker.done() + for lane in lanes + if lane.worker is not None and lane.worker not in callers and not lane.worker.done() ] - connects = [t for t in self._dispatch_tasks if t is not current and not t.done()] + waits_on_caller = { + lane.worker for lane in lanes if lane.worker is not None and lane.jobs and lane.jobs[0].run in callers + } + connects = [t for t in self._dispatch_tasks if t not in callers and not t.done()] running: list[asyncio.Future[Any]] = [*workers, *connects] - if running: + graced = [task for task in running if task not in waits_on_caller] + if graced: with contextlib.suppress(Exception): - await asyncio.wait(running, timeout=_DISPOSE_GRACE_S) - await _release_tasks(running, current) + await asyncio.wait(graced, timeout=_DISPOSE_GRACE_S) + await _release_tasks(running, callers) self._dispatch_tasks.clear() async def _emit_error(self, error: BaseException) -> None: @@ -1999,15 +2068,23 @@ def _start_connect_handlers(self) -> list[Any]: async def _after_hello(self, pending: list[Any]) -> None: """Await the async ``on_connect`` handlers in order, then start the offline drain when it is on.""" - for index, awaitable in enumerate(pending): - try: - await awaitable - except asyncio.CancelledError: - for rest in pending[index + 1 :]: - _discard_awaitable(rest) - raise - except Exception: - _log.warning("realtime handler raised", exc_info=True) + # Marked as a handler task while the on_connect handlers run, never + # during the drain, not even for tasks they started (see _HandlerMark). + mark = _HandlerMark(asyncio.current_task()) + marked = _HANDLER_TASK.set(mark) + try: + for index, awaitable in enumerate(pending): + try: + await awaitable + except asyncio.CancelledError: + for rest in pending[index + 1 :]: + _discard_awaitable(rest) + raise + except Exception: + _log.warning("realtime handler raised", exc_info=True) + finally: + mark.task = None + _HANDLER_TASK.reset(marked) if self._disposed: return if self._opts.auto_drain_on_connect and self._opts.client is not None: @@ -2059,7 +2136,16 @@ def _dispatch_frame(self, message: dict[str, Any]) -> None: _log.warning("realtime handler raised", exc_info=True) continue if inspect.isawaitable(result): - task = asyncio.ensure_future(result) + # A coroutine runs in a marked task; a handler that returned + # a task or future is its own task already. + if inspect.iscoroutine(result): + coro = result + task = asyncio.ensure_future(_as_handler_task(coro)) + # Cancelled before it started: close the handler's + # coroutine (never awaited) quietly. + task.add_done_callback(_close_if_cancelled(coro)) + else: + task = asyncio.ensure_future(result) self._dispatch_tasks.add(task) task.add_done_callback(self._dispatch_tasks.discard) task.add_done_callback(_log_handler_failure) @@ -2216,6 +2302,8 @@ def _message_done(self) -> None: ) async def _finish_job(self, job: _Job) -> None: + # This task's own context, copied by the tasks its handlers start. + _HANDLER_TASK.set(_HandlerMark(asyncio.current_task())) try: await self._run_job(job) except asyncio.CancelledError: @@ -2951,13 +3039,11 @@ def text(key: str) -> str | None: return None if "step" not in payload or integer_step else "step is not an integer" -async def _release_tasks( - tasks: list[asyncio.Future[Any]], current: asyncio.Future[Any] | None -) -> None: +async def _release_tasks(tasks: list[asyncio.Future[Any]], callers: set[asyncio.Future[Any]]) -> None: """Cancel ``tasks`` and wait for them to finish, so a closed client - leaves nothing behind in the loop. The calling task is skipped: a - handler may close the client from inside one of these tasks.""" - pending = [task for task in tasks if task is not current and not task.done()] + leaves nothing behind in the loop. The callers are skipped: a handler + may close the client from inside one of these tasks.""" + pending = [task for task in tasks if task not in callers and not task.done()] for task in pending: task.cancel() if not pending: diff --git a/src/agentchatme/_version.py b/src/agentchatme/_version.py index 6674d56..99b1ae0 100644 --- a/src/agentchatme/_version.py +++ b/src/agentchatme/_version.py @@ -5,4 +5,4 @@ test suite asserts they match. """ -VERSION = "1.3.1" +VERSION = "1.3.2" diff --git a/src/agentchatme/integration/receive_loop.py b/src/agentchatme/integration/receive_loop.py index e81d0c0..a4a920c 100644 --- a/src/agentchatme/integration/receive_loop.py +++ b/src/agentchatme/integration/receive_loop.py @@ -508,7 +508,9 @@ def __init__( self._cycle_timeout_s = ( _timeout_option(cycle_timeout_ms, CYCLE_TIMEOUT_MS, "cycle_timeout_ms") / 1000.0 ) - # Time spent starting turns / runs (excluded from the cycle watchdog). + # Time the running cycle spends starting its own turns or its run + # (left out by the cycle watchdog). An admission _pump starts runs + # outside any cycle and is not counted here. self._turn_depth = 0 self._turn_since = 0.0 self._turn_clock = 0.0 @@ -816,8 +818,10 @@ def _turn_seconds(self) -> float: @contextlib.contextmanager def _inside_turn(self) -> Iterator[None]: - """Time the cycle spends starting a turn or running a run: not - counted by the watchdog.""" + """Time the running cycle spends starting a turn or running a run: + not counted by the watchdog. Only the cycle's own: :meth:`_pump` + admits waiting turns as its own task, and an admission hanging there + must never keep the watchdog from abandoning a cycle that hangs.""" if self._turn_depth == 0: self._turn_since = time.monotonic() self._turn_depth += 1 @@ -1098,7 +1102,9 @@ async def _launch( self._counts["turns_queued"] += 1 return "queued" self._active.add(handle) - if await admit(): + with self._inside_turn(): # the cycle's own admission + started = await admit() + if started: return "started" self._slot_freed(handle) return "refused" @@ -1320,8 +1326,7 @@ async def _admit(self, start: TurnStarter, request: TurnRequest) -> TurnAdmissio whole turn in a worker thread and returns its :class:`TurnEnd`.""" try: if _is_async(start): - with self._inside_turn(): - answer = await start(request) + answer = await start(request) else: return TurnAdmission(started=True, done=asyncio.ensure_future(self._run_sync_turn(start, request))) except Exception as err: diff --git a/src/agentchatme/types/__init__.py b/src/agentchatme/types/__init__.py index 3413f61..148dac3 100644 --- a/src/agentchatme/types/__init__.py +++ b/src/agentchatme/types/__init__.py @@ -96,6 +96,7 @@ MessageSenderKind, MessageStatus, MessageType, + SendableMessageType, SendMessageRequest, ) from .presence import ( @@ -223,6 +224,7 @@ "ReplyDecisionVerdict", "ReportRequest", "SendMessageRequest", + "SendableMessageType", "ServerEvent", "SocketCapability", "TestWakeResult", diff --git a/src/agentchatme/types/message.py b/src/agentchatme/types/message.py index b4bba67..5c27f6c 100644 --- a/src/agentchatme/types/message.py +++ b/src/agentchatme/types/message.py @@ -7,6 +7,11 @@ from pydantic import BaseModel, ConfigDict MessageType = Literal["text", "structured", "file", "system"] +# The types a sender may set on ``send_message``. ``system`` is not one: +# system messages (a group renamed, a member added or removed, a group +# deleted) are written by the platform itself, and the server answers a send +# with ``type="system"`` with 400 VALIDATION_ERROR. +SendableMessageType = Literal["text", "structured", "file"] MessageStatus = Literal["stored", "delivered", "read"] @@ -82,5 +87,5 @@ class SendMessageRequest(_BaseModel): content: MessageContent to: str | None = None conversation_id: str | None = None - type: MessageType | None = None + type: SendableMessageType | None = None metadata: dict[str, Any] | None = None diff --git a/tests/test_integration_kit.py b/tests/test_integration_kit.py index 8fe7e1f..e1887a0 100644 --- a/tests/test_integration_kit.py +++ b/tests/test_integration_kit.py @@ -1267,6 +1267,56 @@ async def slow_start(_request: TurnRequest) -> TurnAdmission: await loop.stop() +@pytest.mark.asyncio +async def test_an_admission_the_pump_started_does_not_hold_off_the_cycle_watchdog() -> None: + # A freed slot is handed on by _pump, its own task, outside any cycle. The + # time its admissions take is not the running cycle's: one that hangs + # there must not keep the watchdog from abandoning a cycle that hangs. + client = _LoopClient([_tray([_card("c1", "m1"), _card("c2", "m2")])]) + turns = _Turns() + never = asyncio.Event() + + async def start_turn(request: TurnRequest) -> TurnAdmission: + if request.conversation_id == "c2": + await never.wait() # the runtime never answers this admission + return TurnAdmission(started=False, error="never answered") + return await turns(request) + + checks = 0 + + async def readiness() -> Readiness: + nonlocal checks + checks += 1 + if checks == 2: + await never.wait() # the second cycle never gets past its readiness check + return Readiness(ready=True) + + loop = _loop( + client, + call_model=lambda _p: _answer(("c1", "reply"), ("c2", "reply")), + start_turn=start_turn, + readiness=readiness, + cycle_timeout_ms=50, + ) + await loop.start() + await _cycle(loop) + assert [r.conversation_id for r in turns.requests] == ["c1"] # c2 waits for the slot + turns.ends[0].set_result(TurnEnd(status="failed")) # c1 ends: the pump admits c2, which hangs + await _eventually( + lambda: loop.status().counters["turns_waiting"] == 0 and loop.status().counters["turns_active"] == 1, + "the pump to be admitting c2", + ) + loop.wake() # c1 is gated again, and this cycle hangs + await _eventually( + lambda: [c.outcome for c in loop.status().recent_cycles] == ["decided", "abandoned"], + "the hung cycle to be abandoned", + timeout=2.0, + ) + assert checks == 2 + never.set() + await loop.stop() + + @pytest.mark.asyncio async def test_status_keeps_the_recent_cycle_outcomes() -> None: client = _LoopClient([_tray([])]) diff --git a/tests/test_public_surface.py b/tests/test_public_surface.py index 2be7666..7bd2005 100644 --- a/tests/test_public_surface.py +++ b/tests/test_public_surface.py @@ -25,3 +25,20 @@ def test_internal_webhooks_are_not_publicly_exposed() -> None: "WebhookPayload", ): assert not hasattr(public_types, type_name) + + +def test_a_send_cannot_carry_the_system_type() -> None: + # The server refuses type="system" on POST /v1/messages (400 + # VALIDATION_ERROR): system messages are the platform's own. + from typing import get_args + + import pytest + from pydantic import ValidationError + + assert set(get_args(public_types.SendableMessageType)) == {"text", "structured", "file"} + assert set(get_args(public_types.MessageType)) == {"text", "structured", "file", "system"} # received + for sendable in ("text", "structured", "file"): + request = public_types.SendMessageRequest(client_msg_id="c", content={"text": "x"}, to="@a", type=sendable) + assert request.type == sendable + with pytest.raises(ValidationError): + public_types.SendMessageRequest(client_msg_id="c", content={"text": "x"}, to="@a", type="system") # pyright: ignore[reportArgumentType] diff --git a/tests/test_realtime.py b/tests/test_realtime.py index 97eeff2..f9bbb78 100644 --- a/tests/test_realtime.py +++ b/tests/test_realtime.py @@ -517,6 +517,250 @@ async def test_on_disconnect_fires_on_close() -> None: await rt.disconnect() +@pytest.mark.asyncio +async def test_disconnect_from_a_message_handler_does_not_wait_on_itself() -> None: + # The handler's own lane waits on the handler, which is waiting in + # disconnect(): giving that lane the dispose grace only ran it out (1 s). + rt, ws = _make_client() + took: list[float] = [] + + async def handler(_msg: dict[str, Any]) -> None: + started = time.monotonic() + await rt.disconnect() + took.append(time.monotonic() - started) + + rt.on("message.new", handler) + await rt.connect() + await _flush() + await ws.push({"type": "hello.ok"}) + await _flush() + await ws.push({"type": "message.new", "payload": {"id": "m1", "conversation_id": "c1", "seq": 1}}) + await eventually(lambda: took, "the handler's disconnect() to return") + assert rt.state == "stopped" + assert took[0] < 0.5, f"disconnect() from the handler took {took[0]:.2f}s" + + +@pytest.mark.parametrize("through", ["ensure_future", "gather", "wait_for"]) +@pytest.mark.asyncio +async def test_disconnect_awaited_through_a_task_of_the_handlers_own_is_still_its_callers(through: str) -> None: + # The handler awaits disconnect() through a task it started (wait_for runs + # its coroutine as a task before Python 3.12). The caller is still known: + # its own task is neither waited for nor cancelled. + rt, ws = _make_client() + took: list[float] = [] + after: list[str] = [] + + async def handler(_msg: dict[str, Any]) -> None: + started = time.monotonic() + if through == "ensure_future": + await asyncio.ensure_future(rt.disconnect()) + elif through == "gather": + await asyncio.gather(rt.disconnect()) + else: + await asyncio.wait_for(rt.disconnect(), timeout=5) + took.append(time.monotonic() - started) + after.append("the handler went on") + + rt.on("message.new", handler) + await rt.connect() + await _flush() + await ws.push({"type": "hello.ok"}) + await _flush() + await ws.push({"type": "message.new", "payload": {"id": "m1", "conversation_id": "c1", "seq": 1}}) + await eventually(lambda: took, "the handler's disconnect() to return") + assert after == ["the handler went on"] # not cancelled + assert rt.state == "stopped" + assert took[0] < 0.5, f"disconnect() through {through} took {took[0]:.2f}s" + + +@pytest.mark.parametrize("kind", ["frame", "on_connect"]) +@pytest.mark.asyncio +async def test_a_frame_or_on_connect_handler_awaiting_disconnect_through_a_task_is_its_caller(kind: str) -> None: + rt, ws = _make_client() + took: list[float] = [] + after: list[str] = [] + + async def handler(*_args: Any) -> None: + started = time.monotonic() + await asyncio.gather(rt.disconnect()) + took.append(time.monotonic() - started) + after.append("the handler went on") + + if kind == "frame": + rt.on("presence.update", handler) + else: + rt.on_connect(handler) + await rt.connect() + await _flush() + await ws.push({"type": "hello.ok"}) + await _flush() + if kind == "frame": + await ws.push({"type": "presence.update", "payload": {"handle": "@alice", "status": "online"}}) + await eventually(lambda: took, "the handler's disconnect() to return") + assert after == ["the handler went on"] # not cancelled + assert rt.state == "stopped" + assert took[0] < 0.5, f"disconnect() from the {kind} handler took {took[0]:.2f}s" + + +@pytest.mark.asyncio +async def test_a_frame_handler_that_returns_a_task_is_still_its_own_caller() -> None: + # The handler hands back a task it started; that task is the dispatch + # task, and it awaits disconnect() directly. + rt, ws = _make_client() + took: list[float] = [] + + async def body(_msg: dict[str, Any]) -> None: + started = time.monotonic() + await rt.disconnect() + took.append(time.monotonic() - started) + + rt.on("presence.update", lambda msg: asyncio.ensure_future(body(msg))) + await rt.connect() + await _flush() + await ws.push({"type": "hello.ok"}) + await _flush() + await ws.push({"type": "presence.update", "payload": {"handle": "@alice", "status": "online"}}) + await eventually(lambda: took, "the handler's disconnect() to return") + assert took[0] < 0.5, f"disconnect() took {took[0]:.2f}s" + + +@pytest.mark.asyncio +async def test_a_task_an_on_connect_handler_started_does_not_shield_the_drain() -> None: + # The mark lasts only while the on_connect handlers run: a task one of + # them started, calling disconnect() during the drain, gets the drain + # cancelled like any other owned task. + class HeldSync(MockAsyncClient): + def __init__(self) -> None: + super().__init__() + self.entered = asyncio.Event() + self.release = asyncio.Event() + + async def sync(self, **kwargs: Any) -> list[dict[str, Any]]: + self.sync_calls.append(kwargs) + self.entered.set() + await self.release.wait() + return [] + + api = HeldSync() + rt, ws = _make_client(client=api, auto_drain_on_connect=True) + phase: list[asyncio.Future[Any]] = [] + asked: list[asyncio.Future[None]] = [] + + async def ask_during_the_drain() -> None: + await api.entered.wait() + await rt.disconnect() + + async def on_connect() -> None: + task = asyncio.current_task() + assert task is not None + phase.append(task) # the task running the on_connect handlers, then the drain + asked.append(asyncio.ensure_future(ask_during_the_drain())) + + rt.on_connect(on_connect) + await rt.connect() + await _flush() + await ws.push({"type": "hello.ok"}) + await asyncio.wait_for(asked_done(asked), timeout=5) + assert rt.state == "stopped" + assert phase[0].done() # the drain was cancelled, not left running + api.release.set() + + +async def asked_done(asked: list[asyncio.Future[None]]) -> None: + await eventually(lambda: asked, "the on_connect handler to start its task") + await asked[0] + + +@pytest.mark.asyncio +async def test_a_handler_that_asks_for_disconnect_and_goes_on_is_its_caller() -> None: + # Fire and forget: the handler that started disconnect() is its caller, + # as when it awaits it: neither waited for nor cancelled. + rt, ws = _make_client() + finished = asyncio.Event() + cancelled: list[bool] = [] + asked: list[asyncio.Future[None]] = [] + + async def handler(_msg: dict[str, Any]) -> None: + asked.append(asyncio.ensure_future(rt.disconnect())) # not awaited + try: + await asyncio.sleep(0.2) # its own wrap-up, after asking + except asyncio.CancelledError: + cancelled.append(True) + raise + finished.set() + + rt.on("message.new", handler) + await rt.connect() + await _flush() + await ws.push({"type": "hello.ok"}) + await _flush() + await ws.push({"type": "message.new", "payload": {"id": "m1", "conversation_id": "c1", "seq": 1}}) + await eventually(lambda: rt.state == "stopped", "disconnect() to run") + await asyncio.wait_for(finished.wait(), timeout=5) + assert cancelled == [] + assert asked[0].done() + + +@pytest.mark.asyncio +async def test_disconnect_from_a_message_handler_still_gives_other_handlers_their_grace() -> None: + rt, ws = _make_client() + order: list[str] = [] + took: list[float] = [] + c2_running = asyncio.Event() + + async def handler(msg: dict[str, Any]) -> None: + if msg["payload"]["conversation_id"] == "c2": + c2_running.set() + await asyncio.sleep(0.15) # inside the 1 s grace + order.append("c2 finished") + return + started = time.monotonic() + await rt.disconnect() + took.append(time.monotonic() - started) + order.append("c1's disconnect() returned") + + rt.on("message.new", handler) + await rt.connect() + await _flush() + await ws.push({"type": "hello.ok"}) + await _flush() + await ws.push({"type": "message.new", "payload": {"id": "m2", "conversation_id": "c2", "seq": 1}}) + await c2_running.wait() + await ws.push({"type": "message.new", "payload": {"id": "m1", "conversation_id": "c1", "seq": 1}}) + await eventually(lambda: took, "the handler's disconnect() to return") + assert order == ["c2 finished", "c1's disconnect() returned"] # c2 was waited for, not cancelled + assert took[0] < 0.8, f"disconnect() from the handler took {took[0]:.2f}s" + + +@pytest.mark.asyncio +async def test_disconnect_from_a_message_handler_never_starts_the_next_message_in_its_lane() -> None: + rt, ws = _make_client() + entered: list[str] = [] + second_queued = asyncio.Event() + returned = asyncio.Event() + + async def handler(msg: dict[str, Any]) -> None: + entered.append(msg["payload"]["id"]) + if msg["payload"]["id"] == "m1": + await second_queued.wait() + await rt.disconnect() + returned.set() + + rt.on("message.new", handler) + await rt.connect() + await _flush() + await ws.push({"type": "hello.ok"}) + await _flush() + await ws.push({"type": "message.new", "payload": {"id": "m1", "conversation_id": "c1", "seq": 1}}) + await ws.push({"type": "message.new", "payload": {"id": "m2", "conversation_id": "c1", "seq": 2}}) + await eventually(lambda: entered == ["m1"] and len(rt._lanes.get("conversation:c1", _realtime._Lane()).jobs) == 2, "m2 to wait behind m1") + second_queued.set() + await asyncio.wait_for(returned.wait(), timeout=5) + await asyncio.sleep(0.05) # negative check: nothing more starts + assert entered == ["m1"] + assert rt.state == "stopped" + + # ─────────────── Offline drain (bare-array wire) ───────────────