Skip to content

Automate browser based workflows with AI

perf(record): event-driven message pump instead of 1ms busy-poll drain (#7005)

Cindy Li8a8af0d4af65
diff --git a/skyvern/forge/sdk/routes/streaming/channels/message.py b/skyvern/forge/sdk/routes/streaming/channels/message.py
index 8d04ab9b1..e52edaf38 100644
--- a/skyvern/forge/sdk/routes/streaming/channels/message.py
+++ b/skyvern/forge/sdk/routes/streaming/channels/message.py
@@ -39,7 +39,6 @@ from skyvern.forge.sdk.routes.streaming.verify import (
verify_workflow_run,
)
from skyvern.forge.sdk.schemas.persistent_browser_sessions import AddressablePersistentBrowserSession
-from skyvern.forge.sdk.utils.aio import collect
from skyvern.forge.sdk.workflow.models.workflow import WorkflowRun
from skyvern.services.browser_recording.session_registry import interpretation_registry
from skyvern.services.browser_recording.types import RecordingDraftStep, RecordingInterpretationUpdate
@@ -320,10 +319,7 @@ MessageOut = (
)
-ChannelMessage = MessageIn | MessageOut
-
-
-def reify_channel_message(data: dict) -> ChannelMessage:
+def reify_channel_message(data: dict) -> MessageIn:
kind = data.get("kind", None)
match kind:
@@ -422,7 +418,10 @@ class MessageChannel:
organization_id: str
websocket: WebSocket
# --
- out_queue: asyncio.Queue[MessageOut] = dataclasses.field(default_factory=asyncio.Queue) # warn: unbounded
+ # Every outbound frame goes through here so backend_to_frontend is the single
+ # websocket writer. Carries MessageOut (serialized by the pump) or a pre-built
+ # dict for out-of-band frames (clipboard) that aren't modeled as MessageOut.
+ out_queue: asyncio.Queue[MessageOut | dict] = dataclasses.field(default_factory=asyncio.Queue) # warn: unbounded
browser_session: AddressablePersistentBrowserSession | None = None
workflow_run: WorkflowRun | None = None
@@ -467,84 +466,6 @@ class MessageChannel:
return True
- async def drain(self) -> list[dict | MessageOut]:
- datums: list[dict | MessageOut] = []
-
- result = await asyncio.gather(
- self.receive_from_out_queue(),
- self.receive_from_user(),
- )
-
- # NOTE(jdo): mypy seems to be unable to infer this, whereas pylance has
- # no issue; added explicit type hints here to help mypy out.
- out_queue: list[MessageOut] = result[0]
- in_queue: list[dict] = result[1]
-
- for out_message in out_queue:
- datums.append(out_message)
-
- for in_message in in_queue:
- if isinstance(in_message, dict):
- datums.append(in_message)
- else:
- LOG.error(
- f"{self.class_name} drain dropping user message: unexpected result type: {type(in_message)}",
- message=in_message,
- **self.identity,
- )
-
- if datums:
- LOG.debug(f"{self.class_name} Drained {len(datums)} messages from message channel.", **self.identity)
-
- return datums
-
- async def receive_from_user(self) -> list[dict]:
- datums: list[dict] = []
-
- while True:
- try:
- data = await asyncio.wait_for(self.websocket.receive_json(), timeout=0.001)
- datums.append(data)
- except asyncio.TimeoutError:
- break
- except RuntimeError as ex:
- if "not connected" in str(ex).lower():
- break
- except WebSocketDisconnect:
- LOG.warning(f"{self.class_name} Disconnected while receiving message from channel", **self.identity)
- break
- except Exception:
- LOG.exception(f"{self.class_name} Failed to receive message from message channel", **self.identity)
- break
-
- return datums
-
- async def receive_from_out_queue(self) -> list[MessageOut]:
- datums: list[MessageOut] = []
-
- while True:
- try:
- data = await asyncio.wait_for(self.out_queue.get(), timeout=0.001)
- datums.append(data)
- except asyncio.TimeoutError:
- break
- except asyncio.QueueEmpty:
- break
-
- return datums
-
- def receive_from_out_queue_nowait(self) -> list[MessageOut]:
- datums: list[MessageOut] = []
-
- while True:
- try:
- data = self.out_queue.get_nowait()
- datums.append(data)
- except asyncio.QueueEmpty:
- break
-
- return datums
-
# async def send(self, *, messages: list[dict]) -> t.Self:
async def send(self, *, messages: list[MessageOut]) -> t.Self:
for message in messages:
@@ -560,28 +481,14 @@ class MessageChannel:
async def ask_for_clipboard(self) -> None:
LOG.info(f"{self.class_name} Sending ask-for-clipboard to message channel", **self.identity)
-
- try:
- await self.websocket.send_json(
- {
- "kind": "ask-for-clipboard",
- }
- )
- except Exception:
- LOG.exception(f"{self.class_name} Failed to send ask-for-clipboard to message channel", **self.identity)
+ # Enqueue rather than write directly: backend_to_frontend is the sole
+ # websocket writer, so this can't race the pump mid-frame (this method is
+ # called from the VNC channel task, a different task than the pump).
+ self.out_queue.put_nowait({"kind": "ask-for-clipboard"})
async def send_copied_text(self, copied_text: str) -> None:
LOG.info(f"{self.class_name} Sending copied text to message channel", **self.identity)
-
- try:
- await self.websocket.send_json(
- {
- "kind": "copied-text",
- "text": copied_text,
- }
- )
- except Exception:
- LOG.exception(f"{self.class_name} Failed to send copied text to message channel", **self.identity)
+ self.out_queue.put_nowait({"kind": "copied-text", "text": copied_text})
async def loop_stream_messages(message_channel: MessageChannel) -> None:
@@ -596,27 +503,20 @@ async def loop_stream_messages(message_channel: MessageChannel) -> None:
live_interpretation_browser_session_id: str | None = None
async def send(message: MessageOut) -> None:
- if message_channel.websocket.client_state != WebSocketState.CONNECTED:
- return
-
- data = message_to_dict(message)
+ # Single-writer: enqueue only; backend_to_frontend is the sole task that
+ # writes to the websocket, so responses and out-of-band messages (event
+ # echoes, interpretation updates) cannot interleave mid-frame.
+ message_channel.send_nowait(messages=[message])
- try:
- await message_channel.websocket.send_json(data)
- except WebSocketDisconnect:
- pass
- except Exception:
- LOG.exception("MessageChannel: failed to send data.")
-
- async def handle_data(data: dict | MessageOut) -> None:
+ async def handle_data(data: object) -> None:
nonlocal class_name
nonlocal exfiltration_channel
nonlocal live_interpretation_browser_session_id
- message: ChannelMessage
+ message: MessageIn
- if isinstance(data, MessageOut):
- message = data
- elif isinstance(data, dict):
+ # receive_json returns whatever the client's JSON parses to — a top-level
+ # array/string/number is possible, so the guard is load-bearing.
+ if isinstance(data, dict):
try:
message = reify_channel_message(data)
except ValueError:
@@ -624,7 +524,7 @@ async def loop_stream_messages(message_channel: MessageChannel) -> None:
return
else:
LOG.error(
- f"{class_name} cannot handle data: expected dict or MessageOut, got {type(data)}",
+ f"{class_name} cannot handle data: expected dict, got {type(data)}",
**message_channel.identity,
)
return
@@ -738,12 +638,6 @@ async def loop_stream_messages(message_channel: MessageChannel) -> None:
vnc_channel=vnc_channel,
).start()
- case MessageKind.BROWSER_TABS:
- await send(message)
-
- case MessageKind.BROWSER_URL:
- await send(message)
-
case MessageKind.CEDE_CONTROL:
vnc_channel = get_vnc_channel(message_channel.client_id)
@@ -853,15 +747,6 @@ async def loop_stream_messages(message_channel: MessageChannel) -> None:
if exfiltration_channel is not None:
await exfiltration_channel.rearm_all_pages()
- case MessageKind.ERROR:
- await send(message)
-
- case MessageKind.EXFILTRATED_EVENT:
- await send(message)
-
- case MessageKind.RECORDING_INTERPRETATION_UPDATE:
- await send(message)
-
case MessageKind.GET_BROWSER_URL:
try:
async with execution_for_message_channel(message_channel) as execute:
@@ -937,9 +822,6 @@ async def loop_stream_messages(message_channel: MessageChannel) -> None:
)
await send_error(message.kind, "Failed to reload.")
- case MessageKind.SCREENSHOT:
- await send(message)
-
case MessageKind.TAKE_CONTROL:
LOG.info(f"{class_name} processing take-control message.", **message_channel.identity)
vnc_channel = get_vnc_channel(message_channel.client_id)
@@ -975,37 +857,75 @@ async def loop_stream_messages(message_channel: MessageChannel) -> None:
while message_channel.is_open:
try:
- datums = await message_channel.drain()
-
- for data in datums:
- if not isinstance(data, (dict, MessageOut)):
- LOG.error(
- f"{class_name} cannot handle message: expected dict or MessageOut, got {type(data)}",
- **message_channel.identity,
- )
- continue
-
- await handle_data(data)
-
+ data = await message_channel.websocket.receive_json()
+ await handle_data(data)
except WebSocketDisconnect:
LOG.debug(f"{class_name} frontend disconnected.", **message_channel.identity)
raise
except ConnectionClosedError:
LOG.debug(f"{class_name} frontend closed channel.", **message_channel.identity)
raise
+ except RuntimeError as ex:
+ # Starlette raises a bare RuntimeError when receive() races a close.
+ if "not connected" in str(ex).lower():
+ LOG.debug(f"{class_name} frontend no longer connected.", **message_channel.identity)
+ return
+ LOG.exception(f"{class_name} An unexpected exception occurred.", **message_channel.identity)
+ raise
except Exception:
LOG.exception(f"{class_name} An unexpected exception occurred.", **message_channel.identity)
raise
+ async def backend_to_frontend() -> None:
+ LOG.debug(f"{class_name} starting backend-to-frontend loop.", **message_channel.identity)
+
+ # Sole websocket writer: wakes the moment a message is enqueued instead of
+ # polling, and keeps sending while frontend_to_backend awaits a slow
+ # command handler (no head-of-line blocking for interpretation updates).
+ while message_channel.is_open:
+ message = await message_channel.out_queue.get()
+
+ if message_channel.websocket.client_state != WebSocketState.CONNECTED:
+ return
+
+ # Clipboard frames are enqueued as pre-built dicts; everything else is
+ # a MessageOut that needs serializing (NaN-sanitized) first.
+ data = message if isinstance(message, dict) else message_to_dict(message)
+
+ try:
+ await message_channel.websocket.send_json(data)
+ except WebSocketDisconnect:
+ return
+ except Exception:
+ # The try only wraps the socket write, so a failure here means the
+ # connection is unhealthy (e.g. Starlette's RuntimeError after a
+ # close frame) — end the session instead of log-spinning per message.
+ LOG.exception("MessageChannel: failed to send data.")
+ return
+
loops = [
asyncio.create_task(frontend_to_backend()),
+ asyncio.create_task(backend_to_frontend()),
]
try:
- await collect(loops)
+ # FIRST_COMPLETED (not collect's FIRST_EXCEPTION): a clean return from
+ # either side must also tear down its sibling, which otherwise blocks
+ # forever on receive_json()/out_queue.get().
+ done, _ = await asyncio.wait(loops, return_when=asyncio.FIRST_COMPLETED)
+ for task in done:
+ if task.exception() is not None:
+ raise t.cast(Exception, task.exception())
except Exception:
LOG.exception(f"{class_name} An exception occurred in loop message channel stream.", **message_channel.identity)
finally:
+ # Cancel both loops on every exit path — including when loop_stream_messages
+ # is itself cancelled mid-wait (collect() cancels it when the sibling verify
+ # loop raises). asyncio.wait does NOT cancel the tasks it awaits, so without
+ # this backend_to_frontend would be stranded on out_queue.get() forever.
+ for task in loops:
+ task.cancel()
+ await asyncio.gather(*loops, return_exceptions=True)
LOG.debug(f"{class_name} Closing the message channel stream.", **message_channel.identity)
if exfiltration_channel is not None:
await exfiltration_channel.stop()
diff --git a/tests/unit/forge/sdk/routes/streaming/test_message_reify.py b/tests/unit/forge/sdk/routes/streaming/test_message_reify.py
index 25e6eb24f..285cd7c7e 100644
--- a/tests/unit/forge/sdk/routes/streaming/test_message_reify.py
+++ b/tests/unit/forge/sdk/routes/streaming/test_message_reify.py
@@ -2,12 +2,14 @@
from __future__ import annotations
+import asyncio
import json
import typing as t
from contextlib import asynccontextmanager
from unittest.mock import AsyncMock, MagicMock
import pytest
+from fastapi import WebSocketDisconnect
from starlette.websockets import WebSocketState
from skyvern.config import settings
@@ -27,6 +29,7 @@ from skyvern.forge.sdk.routes.streaming.channels.message import (
MessageInReload,
MessageInTakeScreenshot,
MessageKind,
+ MessageOutBrowserUrl,
MessageOutExfiltratedEvent,
MessageOutRecordingInterpretationUpdate,
loop_stream_messages,
@@ -320,6 +323,14 @@ class TestLocalExecutionChannel:
page.evaluate.assert_not_awaited()
+def _make_loop_websocket() -> MagicMock:
+ websocket = MagicMock()
+ websocket.client_state = WebSocketState.CONNECTED
+ websocket.send_json = AsyncMock()
+ websocket.close = AsyncMock()
+ return websocket
+
+
class TestMessageLoopUrlUpdates:
@pytest.mark.asyncio
@pytest.mark.parametrize(
@@ -338,10 +349,28 @@ class TestMessageLoopUrlUpdates:
expected_kwargs: dict[str, object],
current_url: str,
) -> None:
- websocket = MagicMock()
- websocket.client_state = WebSocketState.CONNECTED
- websocket.send_json = AsyncMock()
- websocket.close = AsyncMock()
+ websocket = _make_loop_websocket()
+ url_sent = asyncio.Event()
+
+ async def send_json(data: dict[str, object]) -> None:
+ if data.get("kind") == "browser-url":
+ url_sent.set()
+
+ websocket.send_json = AsyncMock(side_effect=send_json)
+
+ receive_calls = 0
+
+ async def receive_json() -> dict[str, object]:
+ nonlocal receive_calls
+ receive_calls += 1
+ if receive_calls == 1:
+ return payload
+ # Hold the reader open until the pump has flushed the queued
+ # response, then end the session.
+ await url_sent.wait()
+ raise WebSocketDisconnect(code=1000)
+
+ websocket.receive_json = receive_json
message_channel = MessageChannel(
client_id="client-1",
@@ -349,18 +378,6 @@ class TestMessageLoopUrlUpdates:
websocket=websocket,
)
- drain_calls = 0
-
- async def drain_once_then_close() -> list[dict[str, object]]:
- nonlocal drain_calls
- drain_calls += 1
- if drain_calls == 1:
- return [payload]
- websocket.client_state = WebSocketState.DISCONNECTED
- return []
-
- message_channel.drain = drain_once_then_close # type: ignore[method-assign]
-
execute = AsyncMock()
execute.get_current_url = AsyncMock(return_value=current_url)
@@ -374,7 +391,7 @@ class TestMessageLoopUrlUpdates:
fake_execution_for_message_channel,
)
- await loop_stream_messages(message_channel)
+ await asyncio.wait_for(loop_stream_messages(message_channel), timeout=2)
method = getattr(execute, method_name)
method.assert_awaited_once_with(**expected_kwargs)
@@ -382,6 +399,228 @@ class TestMessageLoopUrlUpdates:
websocket.send_json.assert_any_await({"kind": "browser-url", "url": current_url})
+class TestMessageLoopPump:
+ @pytest.mark.asyncio
+ async def test_outbound_pump_sends_queued_message_without_inbound_traffic(self) -> None:
+ # Regression test for the old busy-poll drain: a queued MessageOut must be
+ # written by the pump waking on put, with zero inbound traffic driving it.
+ websocket = _make_loop_websocket()
+ url_sent = asyncio.Event()
+ release_reader = asyncio.Event()
+
+ async def send_json(data: dict[str, object]) -> None:
+ if data.get("kind") == "browser-url":
+ url_sent.set()
+
+ websocket.send_json = AsyncMock(side_effect=send_json)
+
+ async def receive_json() -> dict[str, object]:
+ await release_reader.wait()
+ raise WebSocketDisconnect(code=1000)
+
+ websocket.receive_json = receive_json
+
+ message_channel = MessageChannel(
+ client_id="client-1",
+ organization_id="org-1",
+ websocket=websocket,
+ )
+
+ loop_task = asyncio.create_task(loop_stream_messages(message_channel))
+ try:
+ message_channel.send_nowait(messages=[MessageOutBrowserUrl(url="https://example.com/queued")])
+ await asyncio.wait_for(url_sent.wait(), timeout=2)
+ finally:
+ release_reader.set()
+ await asyncio.wait_for(loop_task, timeout=2)
+
+ websocket.send_json.assert_any_await({"kind": "browser-url", "url": "https://example.com/queued"})
+
+ @pytest.mark.asyncio
+ async def test_pump_ends_session_on_non_disconnect_send_failure(self) -> None:
+ # A non-WebSocketDisconnect send failure means the socket is unhealthy
+ # (e.g. Starlette's RuntimeError after a close frame); the pump must end
+ # the session rather than dequeue-log-repeat per message.
+ websocket = _make_loop_websocket()
+ websocket.send_json = AsyncMock(side_effect=RuntimeError("send after close"))
+ release_reader = asyncio.Event()
+
+ async def receive_json() -> dict[str, object]:
+ await release_reader.wait()
+ raise WebSocketDisconnect(code=1000)
+
+ websocket.receive_json = receive_json
+
+ message_channel = MessageChannel(
+ client_id="client-1",
+ organization_id="org-1",
+ websocket=websocket,
+ )
+
+ message_channel.send_nowait(messages=[MessageOutBrowserUrl(url="https://example.com/poison")])
+
+ # The pump's send failure alone must tear the session down — the reader
+ # is never released.
+ await asyncio.wait_for(loop_stream_messages(message_channel), timeout=2)
+
+ websocket.send_json.assert_awaited_once()
+
+ @pytest.mark.asyncio
+ async def test_disconnect_exits_cleanly_while_pump_idle(self) -> None:
+ # The pump blocks on out_queue.get(); a client disconnect must cancel it
+ # and return promptly instead of hanging the session task.
+ websocket = _make_loop_websocket()
+
+ async def receive_json() -> dict[str, object]:
+ raise WebSocketDisconnect(code=1001)
+
+ websocket.receive_json = receive_json
+
+ message_channel = MessageChannel(
+ client_id="client-1",
+ organization_id="org-1",
+ websocket=websocket,
+ )
+
+ await asyncio.wait_for(loop_stream_messages(message_channel), timeout=2)
+
+ websocket.close.assert_awaited()
+
+ @pytest.mark.asyncio
+ async def test_outbound_flows_while_inbound_handler_blocked(self, monkeypatch: pytest.MonkeyPatch) -> None:
+ # Head-of-line fix: an out_queue message must reach the client while the
+ # reader is still awaiting a slow inbound command handler.
+ websocket = _make_loop_websocket()
+ handler_started = asyncio.Event()
+ handler_gate = asyncio.Event()
+ url_sent = asyncio.Event()
+
+ async def send_json(data: dict[str, object]) -> None:
+ if data.get("kind") == "browser-url":
+ url_sent.set()
+
+ websocket.send_json = AsyncMock(side_effect=send_json)
+
+ receive_calls = 0
+
+ async def receive_json() -> dict[str, object]:
+ nonlocal receive_calls
+ receive_calls += 1
+ if receive_calls == 1:
+ return {"kind": "take-screenshot"}
+ raise WebSocketDisconnect(code=1000)
+
+ websocket.receive_json = receive_json
+
+ message_channel = MessageChannel(
+ client_id="client-1",
+ organization_id="org-1",
+ websocket=websocket,
+ )
+
+ async def slow_screenshot() -> str:
+ handler_started.set()
+ await handler_gate.wait()
+ return "b64-screenshot"
+
+ execute = AsyncMock()
+ execute.take_screenshot = slow_screenshot
+
+ @asynccontextmanager
+ async def fake_execution_for_message_channel(_: MessageChannel) -> t.AsyncIterator[AsyncMock]:
+ yield execute
+
+ monkeypatch.setattr(
+ message_module,
+ "execution_for_message_channel",
+ fake_execution_for_message_channel,
+ )
+
+ loop_task = asyncio.create_task(loop_stream_messages(message_channel))
+ try:
+ await asyncio.wait_for(handler_started.wait(), timeout=2)
+ # Reader is parked inside the screenshot handler; the pump must
+ # still deliver this immediately.
+ message_channel.send_nowait(messages=[MessageOutBrowserUrl(url="https://example.com/live")])
+ await asyncio.wait_for(url_sent.wait(), timeout=2)
+ assert not handler_gate.is_set()
+ finally:
+ handler_gate.set()
+ await asyncio.wait_for(loop_task, timeout=2)
+
+ websocket.send_json.assert_any_await({"kind": "browser-url", "url": "https://example.com/live"})
+
+ @pytest.mark.asyncio
+ async def test_external_cancellation_does_not_strand_pump(self) -> None:
+ # collect() cancels loop_stream_messages when a sibling loop (e.g. verify)
+ # raises. That cancellation lands mid-await on asyncio.wait, which does not
+ # cancel the tasks it awaits — the teardown must cancel both loops in its
+ # finally so backend_to_frontend isn't left blocked on out_queue.get().
+ websocket = _make_loop_websocket()
+ reader_started = asyncio.Event()
+
+ async def receive_json() -> dict[str, object]:
+ reader_started.set()
+ await asyncio.Event().wait() # block forever; out_queue is also empty
+
+ websocket.receive_json = receive_json
+
+ message_channel = MessageChannel(
+ client_id="client-1",
+ organization_id="org-1",
+ websocket=websocket,
+ )
+
+ loop_task = asyncio.create_task(loop_stream_messages(message_channel))
+ await asyncio.wait_for(reader_started.wait(), timeout=2)
+
+ loop_task.cancel()
+ with pytest.raises(asyncio.CancelledError):
+ await asyncio.wait_for(loop_task, timeout=2)
+
+ # By the time the cancellation propagates out, the finally has cancelled
+ # and gathered both child loops — nothing left running.
+ leftover = [t for t in asyncio.all_tasks() if t is not asyncio.current_task() and not t.done()]
+ assert leftover == []
+ websocket.close.assert_awaited()
+
+ @pytest.mark.asyncio
+ async def test_clipboard_frames_go_through_the_pump(self) -> None:
+ # Sole-writer invariant: clipboard sends (called from the VNC task) must
+ # enqueue and be written by the pump, never write the websocket directly.
+ websocket = _make_loop_websocket()
+ copied_sent = asyncio.Event()
+ release_reader = asyncio.Event()
+
+ async def send_json(data: dict[str, object]) -> None:
+ if data.get("kind") == "copied-text":
+ copied_sent.set()
+
+ websocket.send_json = AsyncMock(side_effect=send_json)
+
+ async def receive_json() -> dict[str, object]:
+ await release_reader.wait()
+ raise WebSocketDisconnect(code=1000)
+
+ websocket.receive_json = receive_json
+
+ message_channel = MessageChannel(
+ client_id="client-1",
+ organization_id="org-1",
+ websocket=websocket,
+ )
+
+ loop_task = asyncio.create_task(loop_stream_messages(message_channel))
+ try:
+ await message_channel.send_copied_text("hello clipboard")
+ await asyncio.wait_for(copied_sent.wait(), timeout=2)
+ finally:
+ release_reader.set()
+ await asyncio.wait_for(loop_task, timeout=2)
+
+ websocket.send_json.assert_any_await({"kind": "copied-text", "text": "hello clipboard"})
+
+
class TestMessageToDictJsonSafety:
def test_non_finite_floats_become_null(self) -> None:
msg = MessageOutExfiltratedEvent(