From a785b68dfae7330b1cf79fc12adc89949e2ef613 Mon Sep 17 00:00:00 2001 From: Farhan Date: Sat, 21 Nov 2026 13:01:26 +0000 Subject: [PATCH 01/13] Await the results of browser scripts from background handlers A background event handler can now `await rx.call_script(...)`, `rx.call_function(...)` or `rx.run_script(...)` and get the script's result back, instead of passing a callback that the browser evals. - Event gains an optional `rid`, sent only when the backend awaits the event, so ordinary events serialize as before. Clients cannot set it. - The browser runs the script and answers on a new `result` socket event with `{rid, json}` or `{rid, error}`. It does not await the script in the event queue, so a script waiting on the user holds up nothing. - BrowserCalls keeps the pending calls per token. A result settles a call only for the token it was sent to. A disconnect starts a grace period (browser_call_grace_period); a reconnect within it keeps the calls, since socket.io buffers the result emit. - Awaiting under the state lock (a foreground handler, `async with self`) raises EventHandlerTypeError, as does passing a callback too. - Timeouts default to browser_call_timeout, overridable with timeout=. - Errors raise BrowserScriptError, BrowserResultSerializationError, BrowserDisconnectedError or TimeoutError. Claude-Session: https://claude.ai/code/session_01LwJUCVxPh3ihrnaFn6CWnf --- docs/advanced_onboarding/configuration.md | 9 + docs/api-reference/browser_javascript.md | 60 ++++ news/+await-browser-results.feature.md | 1 + .../news/+await-browser-results.feature.md | 11 + .../reflex-base/src/reflex_base/config.py | 6 + .../src/reflex_base/constants/event.py | 3 + .../src/reflex_base/event/__init__.py | 107 +++++-- .../src/reflex_base/event/context.py | 39 +++ .../event/processor/base_state_processor.py | 60 +++- .../event/processor/browser_calls.py | 179 ++++++++++++ .../event/processor/event_processor.py | 49 +++- .../src/reflex_base/utils/exceptions.py | 29 ++ packages/reflex-frontend/src/utils/state.js | 142 +++++++--- .../reflex-frontend/tests/run_script.test.js | 143 ++++++++++ reflex/app.py | 36 +++ .../tests_playwright/test_call_script.py | 105 +++++++ .../processor/test_base_state_processor.py | 167 +++++++++++ .../event/processor/test_browser_calls.py | 266 ++++++++++++++++++ .../event/processor/test_event_processor.py | 99 +++++++ tests/units/reflex_base/event/test_init.py | 32 +++ tests/units/test_app.py | 97 +++++++ 21 files changed, 1574 insertions(+), 66 deletions(-) create mode 100644 news/+await-browser-results.feature.md create mode 100644 packages/reflex-base/news/+await-browser-results.feature.md create mode 100644 packages/reflex-base/src/reflex_base/event/processor/browser_calls.py create mode 100644 tests/units/reflex_base/event/processor/test_browser_calls.py diff --git a/docs/advanced_onboarding/configuration.md b/docs/advanced_onboarding/configuration.md index 390f0ba6d33..c55ef3b478a 100644 --- a/docs/advanced_onboarding/configuration.md +++ b/docs/advanced_onboarding/configuration.md @@ -46,6 +46,15 @@ config = rx.Config( The setting can also be overridden with `REFLEX_EVENT_LOOP_BLOCKING_THRESHOLD`, for example `REFLEX_EVENT_LOOP_BLOCKING_THRESHOLD=0` to turn detection off. +## Awaited Browser Calls + +A background event handler can [await the result of a browser script](/docs/api-reference/browser-javascript/#awaiting-results). Two settings bound how long it waits: + +- `browser_call_timeout` (default `30.0`): the seconds an awaited call waits for its result before raising `TimeoutError`. A call can override it with `timeout=`. +- `browser_call_grace_period` (default `5.0`): the seconds an awaited call waits for its tab to reconnect after a disconnect before raising `BrowserDisconnectedError`. + +They can also be set with `REFLEX_BROWSER_CALL_TIMEOUT` and `REFLEX_BROWSER_CALL_GRACE_PERIOD`. + ## Environment Variables Any config parameter can be overridden by setting an environment variable with the `REFLEX_` prefix and the parameter name in uppercase. Environment variables take precedence over values set in `rxconfig.py`. diff --git a/docs/api-reference/browser_javascript.md b/docs/api-reference/browser_javascript.md index daa87f3c907..6825e18fa66 100644 --- a/docs/api-reference/browser_javascript.md +++ b/docs/api-reference/browser_javascript.md @@ -141,6 +141,66 @@ The `callback` parameter may be an `EventHandler` with one argument, or a lambda If the callback is None, then no event is triggered. ``` +## Awaiting Results + +A [background event handler](/docs/events/background-events/) can `await` `rx.call_script`, `rx.call_function`, or +`rx.run_script` to get the result directly, instead of passing a callback. The handler continues once the browser sends +the value back, so the code that asks for a value and the code that uses it stay together. If the script returns a +promise, the handler gets the value the promise resolves to. + +```python demo exec +class ViewportState(rx.State): + viewport: str = "" + + @rx.event(background=True) + async def measure(self): + size = await rx.call_script("({w: window.innerWidth, h: window.innerHeight})") + async with self: + self.viewport = f"{size['w']} x {size['h']}" + + +def viewport_demo(): + return rx.hstack( + rx.button("Measure Viewport", on_click=ViewportState.measure), + rx.text(ViewportState.viewport), + ) +``` + +The result travels as JSON: objects become `dict`, arrays become `list`, and `undefined` becomes `None`. Return the +data you need from a DOM element rather than the element itself. + +Await the call outside `async with self`. While the handler holds the state lock, the tab's other events would have to +wait for the browser's answer, so awaiting there raises an error. For the same reason, a regular event handler cannot +await a script. Pass either `callback=` or `await` the result, not both. + +The awaited call raises an exception when no value comes back. The Reflex exceptions are imported from +`reflex.utils.exceptions`: + +- `BrowserScriptError` if the script throws, or the promise it returns is rejected. The exception + carries the Javascript error's `name`, `message` and `stack`. +- `BrowserResultSerializationError` (a subclass of `BrowserScriptError`) if the value cannot be + sent as JSON. +- `TimeoutError` if no result arrives within the timeout. The timeout defaults to `browser_call_timeout` in + `rxconfig.py` (30 seconds). Pass `timeout=` to a single call to override it, or `timeout=None` to wait as long as it + takes: + + ```python + answer = await rx.call_script("askTheUser()", timeout=None) + ``` + +- `BrowserDisconnectedError` (a `ConnectionError`) if the tab is not connected when the call is + made. The same error is raised if the tab disconnects and does not reconnect within `browser_call_grace_period` + (5 seconds). A tab that reconnects in time still delivers its result. A tab that reloads loses the running script, so the + call ends at its timeout. + +```md alert info +# Awaiting results with multiple backend workers + +The browser sends the result to the backend worker its tab is connected to. With several workers sharing state through +Redis, a background task awaits results only from tabs connected to its own worker. Calls to other tabs raise +`BrowserDisconnectedError`. +``` + ## Using React Hooks To use React Hooks directly in a Reflex app, you must subclass `rx.Component`, diff --git a/news/+await-browser-results.feature.md b/news/+await-browser-results.feature.md new file mode 100644 index 00000000000..574ca0e7e6c --- /dev/null +++ b/news/+await-browser-results.feature.md @@ -0,0 +1 @@ +The backend now receives the results of browser scripts that a background event handler awaits (`await rx.call_script(...)`), and keeps those calls alive while their tab reconnects. diff --git a/packages/reflex-base/news/+await-browser-results.feature.md b/packages/reflex-base/news/+await-browser-results.feature.md new file mode 100644 index 00000000000..1b245a63682 --- /dev/null +++ b/packages/reflex-base/news/+await-browser-results.feature.md @@ -0,0 +1,11 @@ +A background event handler can now `await` `rx.call_script`, `rx.call_function` and `rx.run_script` to get the script's result directly, instead of passing a `callback`: + +```python +@rx.event(background=True) +async def measure(self): + size = await rx.call_script("({w: window.innerWidth, h: window.innerHeight})") + async with self: + self.width = size["w"] +``` + +A script error raises `BrowserScriptError`, and a missing result raises `TimeoutError` (`browser_call_timeout` config, or `timeout=` per call). A tab that disconnects and does not reconnect within `browser_call_grace_period` raises `BrowserDisconnectedError`. See [Awaiting Results](https://reflex.dev/docs/api-reference/browser-javascript/#awaiting-results). diff --git a/packages/reflex-base/src/reflex_base/config.py b/packages/reflex-base/src/reflex_base/config.py index bdd66072f6d..839fee0229f 100644 --- a/packages/reflex-base/src/reflex_base/config.py +++ b/packages/reflex-base/src/reflex_base/config.py @@ -203,6 +203,8 @@ class BaseConfig: disable_plugins: List of plugin types to disable in the app. transport: The transport method for client-server communication. event_loop_blocking_threshold: Minimum event-loop blocking duration in seconds to report in development. Set to 0 to disable detection. + browser_call_timeout: Seconds an awaited browser call, such as `await rx.call_script(...)` in a background event handler, waits for the browser's result before raising TimeoutError. A call's own `timeout=` overrides it. + browser_call_grace_period: Seconds an awaited browser call survives its tab disconnecting: a reconnect within it delivers the result, otherwise the call raises BrowserDisconnectedError. """ app_name: str @@ -300,6 +302,10 @@ class BaseConfig: event_loop_blocking_threshold: float = 0.2 + browser_call_timeout: float = 30.0 + + browser_call_grace_period: float = 5.0 + # Whether to skip plugin checks. _skip_plugins_checks: bool = dataclasses.field(default=False, repr=False) diff --git a/packages/reflex-base/src/reflex_base/constants/event.py b/packages/reflex-base/src/reflex_base/constants/event.py index 9c0cf2bd3e5..575088cd666 100644 --- a/packages/reflex-base/src/reflex_base/constants/event.py +++ b/packages/reflex-base/src/reflex_base/constants/event.py @@ -50,6 +50,9 @@ class SocketEvent(SimpleNamespace): PING = "ping" EVENT = "event" CLIENT_ERROR = "client_error" + # Sent by the browser with the result of a call the backend awaits + # (must match RESULT_EVENT in packages/reflex-frontend/src/utils/state.js). + RESULT = "result" # Sent on connect when the frontend was compiled for another state tree # (must match STATE_MISMATCH_EVENT in packages/reflex-frontend/src/utils/state.js). STATE_MISMATCH = "state_mismatch" diff --git a/packages/reflex-base/src/reflex_base/event/__init__.py b/packages/reflex-base/src/reflex_base/event/__init__.py index 63844816912..f0ec7a806ff 100644 --- a/packages/reflex-base/src/reflex_base/event/__init__.py +++ b/packages/reflex-base/src/reflex_base/event/__init__.py @@ -47,6 +47,7 @@ EventHandlerArgTypeMismatchError, MissingAnnotationError, ) +from reflex_base.utils.serializers import serializer from reflex_base.utils.types import ( ArgsSpec, GenericType, @@ -100,6 +101,8 @@ class Event: name: The event name. router_data: The routing data where event occurred. payload: The event payload. + rid: Correlates a frontend event with the result the browser sends + back, set only when the backend awaits that result. """ name: str @@ -108,6 +111,8 @@ class Event: payload: dict[str, Any] = dataclasses.field(default_factory=dict) + rid: str | None = None + @property def state_cls(self) -> "type[BaseState]": """The state class for the event.""" @@ -160,7 +165,33 @@ def from_event_type( return out -_EVENT_FIELDS: set[str] = {f.name for f in dataclasses.fields(Event)} +# The fields a client may set on an event it sends. +_EVENT_FIELDS: set[str] = {"name", "router_data", "payload"} + + +@serializer(to=dict) +def serialize_event(event: Event) -> dict[str, Any]: + """Serialize an event sent to the frontend. + + ``rid`` is included only when set, so an event nobody awaits is sent as + it always was. + + Args: + event: The event. + + Returns: + The serialized event. + """ + serialized = { + "name": event.name, + "router_data": event.router_data, + "payload": event.payload, + } + if event.rid is not None: + serialized["rid"] = event.rid + return serialized + + _EMPTY_EVENTS = LiteralVar.create([]) _EMPTY_EVENT_ACTIONS = LiteralVar.create({}) @@ -2083,29 +2114,50 @@ def download( ) +def _script_kwargs( + callback: "EventType[Any] | None", timeout: float | Unset | None +) -> dict[str, Any]: + """Build the arguments a script event takes besides its code. + + Args: + callback: EventHandler that will receive the result of the script. + timeout: Seconds to wait for the result when it is awaited; left out when unset. + + Returns: + The callback, as the javascript that queues it, and the timeout if set. + """ + kwargs: dict[str, Any] = { + "callback": None + if callback is None + else str( + format.format_queue_events(callback, args_spec=lambda result: [result]) + ) + } + if not isinstance(timeout, Unset): + kwargs["timeout"] = timeout + return kwargs + + def call_script( javascript_code: str | Var[str], callback: "EventType[Any] | None" = None, + *, + timeout: float | Unset | None = Unset(), ) -> EventSpec: """Create an event handler that executes arbitrary javascript code. + Awaited in a background event handler, outside ``async with self``, it + returns the script's result: ``value = await rx.call_script(...)``. + Args: javascript_code: The code to execute. callback: EventHandler that will receive the result of evaluating the javascript code. + timeout: Seconds to wait for the result when it is awaited, or None to + wait until it arrives. Defaults to ``rx.Config.browser_call_timeout``. Returns: EventSpec: An event that will execute the client side javascript. """ - callback_kwargs = {"callback": None} - if callback is not None: - callback_kwargs = { - "callback": str( - format.format_queue_events( - callback, - args_spec=lambda result: [result], - ) - ), - } if isinstance(javascript_code, str): # When there is VarData, include it and eval the JS code inline on the client. javascript_code, original_code = ( @@ -2120,34 +2172,30 @@ def call_script( "_call_script", inspect.signature(call_script), javascript_code=javascript_code, - **callback_kwargs, + **_script_kwargs(callback, timeout), ) def call_function( javascript_code: str | Var, callback: "EventType[Any] | None" = None, + *, + timeout: float | Unset | None = Unset(), ) -> EventSpec: """Create an event handler that executes arbitrary javascript code. + Awaited in a background event handler, outside ``async with self``, it + returns the script's result: ``value = await rx.call_function(...)``. + Args: javascript_code: The code to execute. callback: EventHandler that will receive the result of evaluating the javascript code. + timeout: Seconds to wait for the result when it is awaited, or None to + wait until it arrives. Defaults to ``rx.Config.browser_call_timeout``. Returns: EventSpec: An event that will execute the client side javascript. """ - callback_kwargs = {"callback": None} - if callback is not None: - callback_kwargs = { - "callback": str( - format.format_queue_events( - callback, - args_spec=lambda result: [result], - ), - ) - } - javascript_code = ( Var(javascript_code) if isinstance(javascript_code, str) else javascript_code ) @@ -2156,19 +2204,26 @@ def call_function( "_call_function", inspect.signature(call_function), function=javascript_code, - **callback_kwargs, + **_script_kwargs(callback, timeout), ) def run_script( javascript_code: str | Var, callback: "EventType[Any] | None" = None, + *, + timeout: float | Unset | None = Unset(), ) -> EventSpec: """Create an event handler that executes arbitrary javascript code. + Awaited in a background event handler, outside ``async with self``, it + returns the script's result: ``value = await rx.run_script(...)``. + Args: javascript_code: The code to execute. callback: EventHandler that will receive the result of evaluating the javascript code. + timeout: Seconds to wait for the result when it is awaited, or None to + wait until it arrives. Defaults to ``rx.Config.browser_call_timeout``. Returns: EventSpec: An event that will execute the client side javascript. @@ -2177,7 +2232,9 @@ def run_script( Var(javascript_code) if isinstance(javascript_code, str) else javascript_code ) - return call_function(ArgsFunctionOperation.create((), javascript_code), callback) + return call_function( + ArgsFunctionOperation.create((), javascript_code), callback, timeout=timeout + ) def get_event(state: "BaseState", event: str): diff --git a/packages/reflex-base/src/reflex_base/event/context.py b/packages/reflex-base/src/reflex_base/event/context.py index 6cb4624dd51..07677f03c2a 100644 --- a/packages/reflex-base/src/reflex_base/event/context.py +++ b/packages/reflex-base/src/reflex_base/event/context.py @@ -12,6 +12,7 @@ from reflex_base import otel from reflex_base.context.base import BaseContext +from reflex_base.utils.exceptions import BrowserDisconnectedError from reflex_base.utils.format import to_snake_case if TYPE_CHECKING: @@ -77,6 +78,20 @@ async def __call__(self, token: str, *events: Event) -> Any: ... +class CallFrontendProtocol(Protocol): + """Protocol for the call_frontend function in the event context.""" + + async def __call__(self, token: str, event: Event, timeout: float | None) -> Any: + """Run a frontend event in the browser and wait for its result. + + Args: + token: The client token whose browser runs the event. + event: The frontend event to run. + timeout: Seconds to wait for the result, or None to wait until it arrives. + """ + ... + + class EmitDeltaProtocol(Protocol): """Protocol for the emit_delta function in the event context.""" @@ -120,6 +135,11 @@ class EventContext(BaseContext): emit_event_impl: EmitEventProtocol | None = dataclasses.field( default=None, repr=False ) + # Runs a frontend event in the browser and returns its result; None when + # no frontend is attached. + call_frontend_impl: CallFrontendProtocol | None = dataclasses.field( + default=None, repr=False + ) # The app middleware an event passes through before its handler runs, # whether it is queued or awaited inline. middleware: MiddlewareMixin | None = dataclasses.field(default=None, repr=False) @@ -164,6 +184,7 @@ def fork( enqueue_impl=self.enqueue_impl, emit_delta_impl=self.emit_delta_impl, emit_event_impl=self.emit_event_impl, + call_frontend_impl=self.call_frontend_impl, middleware=self.middleware, router_data=router_data or self.router_data, otel_context=otel.capture_context(), @@ -242,6 +263,24 @@ async def emit_event(self, *events: Event) -> None: if self.emit_event_impl is not None: await self.emit_event_impl(self.token, *events) + async def call_frontend(self, event: Event, timeout: float | None) -> Any: + """Run a frontend event in this client's browser and wait for its result. + + Args: + event: The frontend event to run. + timeout: Seconds to wait for the result, or None to wait until it arrives. + + Returns: + The value the browser sent back. + + Raises: + BrowserDisconnectedError: If no frontend is attached to the app. + """ + if self.call_frontend_impl is None: + msg = "No browser is connected to this app, so it cannot run the script." + raise BrowserDisconnectedError(msg) + return await self.call_frontend_impl(self.token, event, timeout) + async def enqueue(self, *event: Event) -> Sequence[EventFuture]: """Enqueue an event handler to be executed. diff --git a/packages/reflex-base/src/reflex_base/event/processor/base_state_processor.py b/packages/reflex-base/src/reflex_base/event/processor/base_state_processor.py index 8af90e5b769..4dc393d087e 100644 --- a/packages/reflex-base/src/reflex_base/event/processor/base_state_processor.py +++ b/packages/reflex-base/src/reflex_base/event/processor/base_state_processor.py @@ -20,6 +20,7 @@ from reflex.istate.proxy import StateProxy from reflex.utils import types from reflex_base import otel +from reflex_base.config import get_config from reflex_base.constants import CompileVars from reflex_base.event import ( _UNDECORATED_STATE_METHOD_HINT, @@ -33,6 +34,7 @@ from reflex_base.event.processor.event_processor import EventProcessor, EventQueueEntry from reflex_base.event.processor.future import EventFuture from reflex_base.registry import RegisteredEventHandler +from reflex_base.utils.exceptions import EventHandlerTypeError from reflex_base.utils.form import form_data_as_dict, transform_form_data from reflex_base.utils.format import format_event_handler from reflex_base.utils.serializers import deserializers @@ -577,6 +579,49 @@ def ensure_locked( return None +# The frontend events whose result the backend can await. +_BROWSER_CALL_EVENTS = frozenset({"_call_script", "_call_function"}) + + +async def _await_browser_call(ctx: EventContext, event: Event) -> Any: + """Run a script in the client's browser and wait for its result. + + Args: + ctx: The active EventContext of the client. + event: The ``_call_script`` or ``_call_function`` event. + + Returns: + The script's result. + + Raises: + EventHandlerTypeError: If the state lock is held, which would hold up + every other event of the client until the browser answers, or the + event also has a result callback. + """ + if ctx.locked_root is not None: + msg = ( + f"`{event.name}` cannot be awaited while the state lock is held, as " + "every other event of this tab would wait for the browser's answer; " + "await it in a background event handler, outside `async with self`." + ) + raise EventHandlerTypeError(msg) + payload = event.payload + if payload.get("callback") is not None: + msg = ( + f"`{event.name}` was given a callback and awaited; pass either " + "callback= or await its result, not both." + ) + raise EventHandlerTypeError(msg) + # _to_event built this payload for this event alone, so it is the + # event's to change. + timeout = ( + payload.pop("timeout") + if "timeout" in payload + else get_config().browser_call_timeout + ) + return await ctx.call_frontend(event, timeout) + + async def execute_event_inline(spec: EventSpec) -> Any: """Run the event a spec describes from inside the active EventContext. @@ -585,22 +630,24 @@ async def execute_event_inline(spec: EventSpec) -> Any: self`` in a background handler, ``app.modify_state``), the handler runs inline on the locked state tree under the caller's context: its yields emit deltas and the events it yields chain under the caller's event. With - no lock held, the event is enqueued and its future awaited. + no lock held, the event is enqueued and its future awaited. A script the + spec runs in the browser (``rx.call_script``, ``rx.call_function``, + ``rx.run_script``) is sent to it, and its result awaited. Args: spec: The event spec to execute. Returns: - The handler's return value. + The handler's return value, or the script's result. Raises: EventHandlerTypeError: If there is no active EventContext for a client (outside an event handler and ``app.modify_state``), the - spec is a frontend-only or upload event, or a background handler - is awaited while the state lock is held (which would deadlock). + spec is another frontend-only event or an upload event, or a + background handler is awaited while the state lock is held (which + would deadlock). """ from reflex_base.registry import RegistrationContext - from reflex_base.utils.exceptions import EventHandlerTypeError try: ctx = EventContext.get() @@ -618,6 +665,8 @@ async def execute_event_inline(spec: EventSpec) -> Any: raise EventHandlerTypeError(msg) event = spec._to_event(ctx.router_data) name = event.name + if name in _BROWSER_CALL_EVENTS: + return await _await_browser_call(ctx, event) if spec.client_handler_name: msg = f"Upload event `{name}` cannot be awaited; use it as an event trigger." raise EventHandlerTypeError(msg) @@ -892,6 +941,7 @@ def _on_disconnect(self, token: str) -> None: Args: token: The disconnected client token. """ + super()._on_disconnect(token) _, on_load_name = _connect_supersedes() for future in self._pending_hydrates.pop(token, {}).values(): future.cancel() diff --git a/packages/reflex-base/src/reflex_base/event/processor/browser_calls.py b/packages/reflex-base/src/reflex_base/event/processor/browser_calls.py new file mode 100644 index 00000000000..6dd08dfd39a --- /dev/null +++ b/packages/reflex-base/src/reflex_base/event/processor/browser_calls.py @@ -0,0 +1,179 @@ +"""The browser calls the backend awaits: frontend events whose result it waits for.""" + +from __future__ import annotations + +import asyncio +import dataclasses +import json +import uuid +from collections.abc import Awaitable, Callable, Mapping +from typing import TYPE_CHECKING, Any + +from reflex_base.utils.exceptions import ( + BrowserDisconnectedError, + BrowserResultSerializationError, + BrowserScriptError, +) + +if TYPE_CHECKING: + from reflex_base.event import Event + +# The ``kind`` of the error the frontend reports for a value JSON cannot carry. +SERIALIZATION_ERROR_KIND = "serialization" + + +@dataclasses.dataclass(slots=True) +class BrowserCalls: + """The browser calls waiting for a result, per client token. + + A result resolves a call only when it comes from the token the call was + sent to, so one tab cannot answer another tab's call. + """ + + # Client token -> request id -> the future its result resolves. + _pending: dict[str, dict[str, asyncio.Future[Any]]] = dataclasses.field( + default_factory=dict + ) + # Client token -> the timer that fails its calls once the grace period + # after a disconnect is over. + _grace_timers: dict[str, asyncio.TimerHandle] = dataclasses.field( + default_factory=dict + ) + + async def call( + self, + token: str, + event: Event, + timeout: float | None, + emit: Callable[[str, Event], Awaitable[Any]], + ) -> Any: + """Send an event to a client and wait for the result the browser sends back. + + Args: + token: The client token to send the event to. + event: The frontend event to run in the browser. + timeout: Seconds to wait for the result, or None to wait until it arrives. + emit: Sends an event to a client. + + Returns: + The value the browser sent back. + + Raises: + TimeoutError: If no result arrives within the timeout. + """ + rid = uuid.uuid4().hex + future = asyncio.get_running_loop().create_future() + calls = self._pending.setdefault(token, {}) + calls[rid] = future + try: + await emit(token, dataclasses.replace(event, rid=rid)) + try: + return await asyncio.wait_for(future, timeout) + except TimeoutError: + msg = ( + f"The browser did not return a result for `{event.name}` " + f"within {timeout} seconds." + ) + raise TimeoutError(msg) from None + finally: + calls.pop(rid, None) + # The token's calls may have been failed on a disconnect already, + # which drops this mapping from _pending. + if not calls and self._pending.get(token) is calls: + del self._pending[token] + if (timer := self._grace_timers.pop(token, None)) is not None: + timer.cancel() + + def resolve(self, token: str, rid: str, outcome: Mapping[str, Any]) -> None: + """Settle a call with the outcome the browser reported for it. + + An outcome for a call that is no longer waiting (it timed out, or the + token never made it) is dropped. + + Args: + token: The client token the outcome came from. + rid: The request id of the call. + outcome: ``{"json": }``, or ``{"error": {"name", + "message", "stack", "kind"}}`` when the script failed. + """ + calls = self._pending.get(token) + if calls is None or (future := calls.pop(rid, None)) is None or future.done(): + return + error = outcome.get("error") + if isinstance(error, Mapping): + error_cls = ( + BrowserResultSerializationError + if error.get("kind") == SERIALIZATION_ERROR_KIND + else BrowserScriptError + ) + future.set_exception( + error_cls( + str(error.get("name", "Error")), + str(error.get("message", "")), + str(error.get("stack", "")), + ) + ) + return + try: + future.set_result(json.loads(outcome["json"])) + except (KeyError, TypeError, ValueError) as e: + future.set_exception( + BrowserResultSerializationError( + type(e).__name__, f"The browser sent a malformed result: {e}" + ) + ) + + def disconnect(self, token: str, grace_period: float) -> None: + """Start the grace period of a client's calls after it disconnected. + + The tab may reconnect within it, and its results then still arrive. + + Args: + token: The disconnected client token. + grace_period: Seconds to wait for the client to reconnect. + """ + if token not in self._pending or token in self._grace_timers: + return + if grace_period <= 0: + self._fail(token) + return + self._grace_timers[token] = asyncio.get_running_loop().call_later( + grace_period, self._fail, token + ) + + def reconnect(self, token: str) -> None: + """End the grace period of a client that connected again. + + Args: + token: The reconnected client token. + """ + if (timer := self._grace_timers.pop(token, None)) is not None: + timer.cancel() + + def close(self) -> None: + """Cancel every pending call, as the backend shuts down.""" + for timer in self._grace_timers.values(): + timer.cancel() + self._grace_timers.clear() + for calls in self._pending.values(): + for future in calls.values(): + future.cancel() + self._pending.clear() + + def _fail(self, token: str) -> None: + """Fail a client's calls: it did not reconnect within the grace period. + + Args: + token: The disconnected client token. + """ + self._grace_timers.pop(token, None) + for future in self._pending.pop(token, {}).values(): + if not future.done(): + future.set_exception( + BrowserDisconnectedError( + "The browser tab disconnected before returning a result." + ) + ) + + +__all__ = ["BrowserCalls"] diff --git a/packages/reflex-base/src/reflex_base/event/processor/event_processor.py b/packages/reflex-base/src/reflex_base/event/processor/event_processor.py index 915c0e05bcd..477663f802d 100644 --- a/packages/reflex-base/src/reflex_base/event/processor/event_processor.py +++ b/packages/reflex-base/src/reflex_base/event/processor/event_processor.py @@ -26,9 +26,11 @@ EVENT_TASK_PREFIX, EventLoopBlockingMonitor, ) +from reflex_base.event.processor.browser_calls import BrowserCalls from reflex_base.event.processor.future import EventFuture from reflex_base.event.processor.timeout import DrainTimeoutManager from reflex_base.registry import RegisteredEventHandler, RegistrationContext +from reflex_base.utils.exceptions import BrowserDisconnectedError logger = logging.getLogger(__name__) @@ -102,6 +104,7 @@ class EventProcessor: middleware: An optional middleware mixin to apply to all events processed by this processor. backend_exception_handler: An optional function to handle exceptions raised during event processing. The function should take an Exception as input and return an EventSpec or list of EventSpecs to be emitted in response, or None to not emit any events. graceful_shutdown_timeout: An optional amount of time in seconds to wait for the queue to drain before forcefully cancelling tasks when stopping the processor. If None, the processor will not wait and will cancel tasks immediately. + browser_call_grace_period: Seconds an awaited browser call waits for its disconnected tab to reconnect before it fails. _queue: The asyncio queue for events to be processed. _queue_task: The task responsible for processing the event queue. @@ -116,6 +119,7 @@ class EventProcessor: ) = None graceful_shutdown_timeout: float | None = None event_loop_blocking_threshold: float = 0 + browser_call_grace_period: float = 5.0 _queue: asyncio.Queue[EventQueueEntry] | None = dataclasses.field( default=None, init=False @@ -148,6 +152,9 @@ class EventProcessor: _blocking_monitor: EventLoopBlockingMonitor | None = dataclasses.field( default=None, init=False, repr=False ) + _browser_calls: BrowserCalls = dataclasses.field( + default_factory=BrowserCalls, init=False, repr=False + ) def configure( self, @@ -177,7 +184,7 @@ def configure( ) raise RuntimeError(msg) - emit_delta_impl = emit_event_impl = None + emit_delta_impl = emit_event_impl = call_frontend_impl = None if event_namespace is not None: async def emit_delta( @@ -212,6 +219,32 @@ async def emit_event(token: str, *events: Event) -> None: emit_event_impl = emit_event + async def call_frontend( + token: str, event: Event, timeout: float | None + ) -> Any: + """Run a frontend event in the browser and wait for its result. + + Args: + token: The client token whose browser runs the event. + event: The frontend event to run. + timeout: Seconds to wait for the result, or None to wait until it arrives. + + Returns: + The value the browser sent back. + + Raises: + BrowserDisconnectedError: If the client is not connected to this backend. + """ + if not event_namespace._is_connected(token): + msg = ( + f"The browser tab is not connected, so `{event.name}` " + "cannot run in it." + ) + raise BrowserDisconnectedError(msg) + return await self._browser_calls.call(token, event, timeout, emit_event) + + call_frontend_impl = call_frontend + if state_manager is None: # For testing use cases, default to a new in-memory state manager if one is not provided. state_manager = StateManagerMemory() @@ -225,6 +258,7 @@ async def emit_event(token: str, *events: Event) -> None: enqueue_impl=self.enqueue_many, emit_delta_impl=emit_delta_impl, emit_event_impl=emit_event_impl, + call_frontend_impl=call_frontend_impl, middleware=self.middleware, ) return self @@ -361,6 +395,7 @@ async def stop(self, graceful_shutdown_timeout: float | None = None) -> None: if not future.done(): future.cancel() self._futures.clear() + self._browser_calls.close() if self._blocking_monitor is not None: self._blocking_monitor.stop() self._blocking_monitor = None @@ -489,10 +524,21 @@ def _on_disconnect(self, token: str) -> None: """Handle a client disconnect without cancelling independent event work. Subclasses may cancel work tied to the disconnected page's lifecycle. + The browser calls awaiting the client's results get a grace period to + reconnect in. Args: token: The disconnected client token. """ + self._browser_calls.disconnect(token, self.browser_call_grace_period) + + def _on_connect(self, token: str) -> None: + """Handle a client connecting, possibly again after a disconnect. + + Args: + token: The connected client token. + """ + self._browser_calls.reconnect(token) async def enqueue_many(self, token: str, *events: Event) -> Sequence[EventFuture]: """Enqueue multiple events to be processed. @@ -565,6 +611,7 @@ async def _emit_delta_impl( enqueue_impl=root.enqueue_impl, emit_delta_impl=_emit_delta_impl, emit_event_impl=root.emit_event_impl, + call_frontend_impl=root.call_frontend_impl, middleware=root.middleware, # Like fork(): the handler span nests under the caller's span # (the upload request, a custom route). diff --git a/packages/reflex-base/src/reflex_base/utils/exceptions.py b/packages/reflex-base/src/reflex_base/utils/exceptions.py index 75368add0eb..835123d369c 100644 --- a/packages/reflex-base/src/reflex_base/utils/exceptions.py +++ b/packages/reflex-base/src/reflex_base/utils/exceptions.py @@ -322,6 +322,35 @@ class ClientStateConflictError(ReflexError, ValueError): """Raised when one client state name is declared with two different defaults.""" +class BrowserScriptError(ReflexError): + """Raised when JavaScript the backend awaits throws in the browser. + + The JavaScript error's name is not mapped to a Python exception type: a + JavaScript ``TypeError`` is not a Python ``TypeError``. + """ + + def __init__(self, name: str, message: str, stack: str = ""): + """Create the error from the JavaScript error the browser reported. + + Args: + name: The JavaScript error's name, such as ``TypeError``. + message: Its message. + stack: Its stack trace, if the browser had one. + """ + super().__init__(f"{name}: {message}") + self.name = name + self.message = message + self.stack = stack + + +class BrowserResultSerializationError(BrowserScriptError): + """Raised when an awaited browser call returns a value JSON cannot carry.""" + + +class BrowserDisconnectedError(ReflexError, ConnectionError): + """Raised when the tab an awaited browser call runs in is not connected.""" + + def __getattr__(name: str) -> Any: """Resolve the deprecated exception names, warning on use. diff --git a/packages/reflex-frontend/src/utils/state.js b/packages/reflex-frontend/src/utils/state.js index 7486b1dac04..4b5f7c706b9 100644 --- a/packages/reflex-frontend/src/utils/state.js +++ b/packages/reflex-frontend/src/utils/state.js @@ -30,6 +30,11 @@ const EVENTURL = env.EVENT; // Socket event names (must match reflex_base/constants/event.py SocketEvent) const CLIENT_ERROR_EVENT = "client_error"; const STATE_MISMATCH_EVENT = "state_mismatch"; +const RESULT_EVENT = "result"; + +// The error kind of a script result JSON cannot carry (must match +// SERIALIZATION_ERROR_KIND in reflex_base/event/processor/browser_calls.py). +const SERIALIZATION_ERROR_KIND = "serialization"; // sessionStorage key with the time of the last automatic reload (must match // LAST_RELOADED_KEY in reflex/state.py: the reload on a frontend error and the @@ -591,6 +596,98 @@ const applyResultCallback = async ( callback(final_result); }; +/** + * Run the script of a _call_script or _call_function event. + * @param event The event whose script to run. + * @param addEvents The late-bound event dispatcher for the script. + * @param socket The socket object to send events on. + * @param navigate The navigate function from useNavigate. + * @param params The params object from useParams. + * @returns The script's completion value, or the function's return value. + */ +const runEventScript = (event, addEvents, socket, navigate, params) => { + if (event.name === "_call_script") { + return runScript( + event.payload.javascript_code, + addEvents, + socket, + navigate, + params, + ); + } + const fn = + typeof event.payload.function === "string" + ? runScript(event.payload.function, addEvents, socket, navigate, params) + : event.payload.function; + return fn(); +}; + +/** + * Describe an error a script threw, for the backend that awaits its result. + * @param error The thrown value, which need not be an Error. + * @param kind The kind of failure, if it is not the script's own. + * @returns The error's name, message and stack. + */ +const describeScriptError = (error, kind = undefined) => ({ + name: error?.name ?? "Error", + message: error instanceof Error ? error.message : String(error), + stack: error?.stack ?? "", + ...(kind === undefined ? {} : { kind }), +}); + +/** + * Serialize a script's result as JSON for the backend that awaits it. + * + * ``undefined`` is sent as ``null``. A DOM node or the window would arrive as + * an empty object, so it is rejected instead, like a value JSON cannot carry. + * @param value The script's result. + * @returns The result as JSON. + */ +const serializeScriptResult = (value) => { + const json = JSON.stringify(value ?? null, (_key, item) => { + if ( + item === globalThis || + (typeof Node !== "undefined" && item instanceof Node) + ) { + throw new TypeError( + "The script returned a DOM node or window, which JSON cannot carry; return the data you need from it instead.", + ); + } + return item; + }); + if (json === undefined) { + throw new TypeError( + `The script returned a ${typeof value}, which JSON cannot carry.`, + ); + } + return json; +}; + +/** + * Run a script the backend awaits and send its result, or its error, back. + * + * The script runs before this returns; its result is awaited and sent after, + * so a script waiting on the user does not hold up the event queue. + * @param socket The socket object to send the result on. + * @param rid The request id the backend awaits the result under. + * @param run Runs the script and returns its result. + */ +const sendScriptResult = async (socket, rid, run) => { + let outcome; + try { + const value = await run(); + try { + outcome = { rid, json: serializeScriptResult(value) }; + } catch (e) { + outcome = { rid, error: describeScriptError(e, SERIALIZATION_ERROR_KIND) }; + } + } catch (e) { + outcome = { rid, error: describeScriptError(e) }; + } + // Buffered by socket.io while disconnected, and sent once it reconnects. + socket?.emit(RESULT_EVENT, outcome); +}; + /** * Build the update_vars_internal event for a synced localStorage var. * @@ -802,49 +899,24 @@ export const applyEvent = async (event, socket, navigate, params) => { return; } - if ( - event.name === "_call_function" && - typeof event.payload.function !== "string" - ) { + if (event.name === "_call_script" || event.name === "_call_function") { + if (event.rid) { + // The backend awaits the result: an error is its to handle. + void sendScriptResult(socket, event.rid, () => + runEventScript(event, addEvents, socket, navigate, params), + ); + return; + } try { await applyResultCallback( event, - event.payload.function(), + runEventScript(event, addEvents, socket, navigate, params), socket, navigate, params, ); } catch (e) { - console.log("_call_function", e); - if (window?.onerror) { - window.onerror(e.message, null, null, null, e); - } - } - return; - } - - if (event.name === "_call_script" || event.name === "_call_function") { - try { - const eval_result = - event.name === "_call_script" - ? runScript( - event.payload.javascript_code, - addEvents, - socket, - navigate, - params, - ) - : runScript( - event.payload.function, - addEvents, - socket, - navigate, - params, - )(); - - await applyResultCallback(event, eval_result, socket, navigate, params); - } catch (e) { - console.log("_call_script", e); + console.log(event.name, e); if (window?.onerror) { window.onerror(e.message, null, null, null, e); } diff --git a/packages/reflex-frontend/tests/run_script.test.js b/packages/reflex-frontend/tests/run_script.test.js index f561ee2f7ca..7691b7f9dc7 100644 --- a/packages/reflex-frontend/tests/run_script.test.js +++ b/packages/reflex-frontend/tests/run_script.test.js @@ -120,3 +120,146 @@ describe("_call_script", () => { expect(seen).toEqual([7]); }); }); + +describe("awaited script results", () => { + const awaited = (event) => { + const socket = { emit: vi.fn() }; + return { + socket, + applied: applyEvent({ ...event, rid: "r1" }, socket, null, null), + // The outcome the backend receives, once the script has settled. + outcome: async () => { + await vi.waitFor(() => expect(socket.emit).toHaveBeenCalledTimes(1)); + const [name, outcome] = socket.emit.mock.calls[0]; + expect(name).toBe("result"); + return outcome; + }, + }; + }; + const script = (code) => ({ + name: "_call_script", + payload: { javascript_code: code, callback: null }, + }); + // The stack trace depends on the run, so it is compared as a placeholder. + const withoutStack = (outcome) => { + expect(typeof outcome.error.stack).toBe("string"); + return { ...outcome, error: { ...outcome.error, stack: "" } }; + }; + + test("sends the script's value back as JSON", async () => { + const { outcome } = awaited(script('({a: [1, 2], b: "x", c: null})')); + expect(await outcome()).toEqual({ + rid: "r1", + json: '{"a":[1,2],"b":"x","c":null}', + }); + }); + + test("sends undefined as null", async () => { + const { outcome } = awaited(script("undefined")); + expect(await outcome()).toEqual({ rid: "r1", json: "null" }); + }); + + test("awaits a promise without holding up the event queue", async () => { + let resolve; + globalThis.pendingResult = new Promise((r) => { + resolve = r; + }); + try { + const { socket, applied, outcome } = awaited( + script("globalThis.pendingResult"), + ); + // applyEvent returns while the promise is pending, so the queue moves on. + await applied; + expect(socket.emit).not.toHaveBeenCalled(); + resolve(5); + expect(await outcome()).toEqual({ rid: "r1", json: "5" }); + } finally { + delete globalThis.pendingResult; + } + }); + + test("calls a _call_function function and sends its value", async () => { + const { outcome } = awaited({ + name: "_call_function", + payload: { function: () => [true], callback: null }, + }); + expect(await outcome()).toEqual({ rid: "r1", json: "[true]" }); + }); + + test("sends an error the script throws to the backend, not window.onerror", async () => { + const onerror = vi.fn(); + window.onerror = onerror; + const { outcome } = awaited(script('throw new RangeError("too far")')); + expect(withoutStack(await outcome())).toEqual({ + rid: "r1", + error: { name: "RangeError", message: "too far", stack: "" }, + }); + expect(onerror).not.toHaveBeenCalled(); + }); + + test("sends a rejected promise as an error", async () => { + const { outcome } = awaited( + script('Promise.reject(new TypeError("refused"))'), + ); + expect(withoutStack(await outcome())).toEqual({ + rid: "r1", + error: { name: "TypeError", message: "refused", stack: "" }, + }); + }); + + test("describes a thrown value that is not an Error", async () => { + const { outcome } = awaited(script('Promise.reject("nope")')); + expect(await outcome()).toEqual({ + rid: "r1", + error: { name: "Error", message: "nope", stack: "" }, + }); + }); + + test.each([ + [ + "a DOM node", + "document.body", + "TypeError", + "The script returned a DOM node or window, which JSON cannot carry; return the data you need from it instead.", + ], + [ + "a DOM node inside a value", + "({el: document.body})", + "TypeError", + "The script returned a DOM node or window, which JSON cannot carry; return the data you need from it instead.", + ], + [ + "the window", + "window", + "TypeError", + "The script returned a DOM node or window, which JSON cannot carry; return the data you need from it instead.", + ], + [ + "a function", + "() => 1", + "TypeError", + "The script returned a function, which JSON cannot carry.", + ], + [ + "a BigInt", + "1n", + "TypeError", + "Do not know how to serialize a BigInt", + ], + ])("rejects %s as a serialization error", async (_what, code, name, message) => { + const { outcome } = awaited(script(code)); + expect(withoutStack(await outcome())).toEqual({ + rid: "r1", + error: { name, message, stack: "", kind: "serialization" }, + }); + }); + + test("a script without a request id still reports errors to window.onerror", async () => { + const onerror = vi.fn(); + window.onerror = onerror; + const socket = { emit: vi.fn() }; + await applyEvent(script("throw new Error('boom')"), socket, null, null); + expect(onerror).toHaveBeenCalledTimes(1); + expect(socket.emit).not.toHaveBeenCalled(); + }); +}); diff --git a/reflex/app.py b/reflex/app.py index 3d9229c599c..367190cdaac 100644 --- a/reflex/app.py +++ b/reflex/app.py @@ -1261,6 +1261,7 @@ async def _setup_event_processor(self) -> AsyncIterator[None]: middleware=self, backend_exception_handler=self.backend_exception_handler, event_loop_blocking_threshold=get_config().event_loop_blocking_threshold, + browser_call_grace_period=get_config().browser_call_grace_period, ) async with self._event_processor.configure( state_manager=state_manager, @@ -2871,6 +2872,21 @@ def on_disconnect(self, sid: str) -> asyncio.Task | None: return task return None + def _is_connected(self, token: str) -> bool: + """Whether a client is connected to this instance of the backend. + + Args: + token: The client token. + + Returns: + True when the token's socket is connected to this instance. + """ + socket_record = self._token_manager.token_to_socket.get(token) + return ( + socket_record is not None + and socket_record.instance_id == self._token_manager.instance_id + ) + async def emit_update( self, update: StateUpdate, token: str, suppress_warnings: bool = False ) -> None: @@ -3110,6 +3126,23 @@ async def on_client_error(self, sid: str, data: Any = None): # handlers (e.g. error trackers) receive client errors too. self.app.frontend_exception_handler(Exception(report)) + async def on_result(self, sid: str, data: Any = None): + """Settle a browser call the backend awaits with the result the browser sent. + + Args: + sid: The Socket.IO session id. + data: ``{"rid": , "json": }``, or + ``{"rid": , "error": {...}}`` when the script failed. + """ + if not isinstance(data, dict) or not isinstance(rid := data.get("rid"), str): + logger.debug(f"Ignoring malformed result payload from SID {sid}.") + return + if (token := self.sid_to_token.get(sid)) is None or ( + processor := self.app._event_processor + ) is None: + return + processor._browser_calls.resolve(token, rid, data) + async def link_token_to_sid( self, sid: str, token: str, *, update_state: bool = True ): @@ -3129,6 +3162,9 @@ async def link_token_to_sid( if new_token: # Duplicate detected, emit new token to client await self.emit("new_token", new_token, to=sid) + elif (processor := self.app._event_processor) is not None: + # A tab reconnecting within the grace period keeps its browser calls. + processor._on_connect(token) # Update client state to apply new sid/token for running background tasks. if update_state and self.app._state is not None: diff --git a/tests/integration/tests_playwright/test_call_script.py b/tests/integration/tests_playwright/test_call_script.py index e9fa0d84444..96dd3719129 100644 --- a/tests/integration/tests_playwright/test_call_script.py +++ b/tests/integration/tests_playwright/test_call_script.py @@ -44,6 +44,44 @@ class CallScriptState(rx.State): external_counter: rx.Field[int] = rx.field(0) value: str = "Initial" last_result: rx.Field[int] = rx.field(0) + awaited: rx.Field[list[str]] = rx.field([]) + + @rx.event(background=True) + async def await_results(self): + from reflex.utils.exceptions import ( + BrowserResultSerializationError, + BrowserScriptError, + ) + + seen: list[str] = [ + repr(await rx.call_script("inline3()")), + repr(await rx.call_script("inline4()")), + repr(await rx.call_function("() => [1, 'two', undefined]")), + repr(await rx.call_script("undefined")), + ] + for code, expected in ( + ("missing_function()", BrowserScriptError), + ("document.body", BrowserResultSerializationError), + ): + try: + await rx.call_script(code) + except expected as e: + seen.append(f"{type(e).__name__}: {e}") + try: + await rx.call_script("new Promise(() => {})", timeout=0.5) + except TimeoutError as e: + seen.append(f"TimeoutError: {e}") + async with self: + self.awaited = seen + + @rx.event(background=True) + async def await_user(self): + # Settled by the test once another event has gone through. + answer = await rx.call_script( + "new Promise((resolve) => { window.answerAwaited = resolve })" + ) + async with self: + self.awaited = [repr(answer)] @rx.event def call_script_callback(self, result): @@ -292,6 +330,25 @@ def index(): id="update_value", ), rx.button("Reset", id="reset", on_click=CallScriptState.reset_), + rx.button( + "await_results", + on_click=CallScriptState.await_results, + id="await_results", + ), + rx.button( + "await_user", on_click=CallScriptState.await_user, id="await_user" + ), + rx.button( + "set_value_busy", + on_click=CallScriptState.set_value("busy"), + id="set_value_busy", + ), + rx.text(CallScriptState.value, id="value"), + rx.text_area( + value=CallScriptState.awaited.join("\n"), + id="awaited", + read_only=True, + ), rx.input( value=CallScriptState.last_result.to_string(), id="last_result", @@ -525,3 +582,51 @@ def test_call_script_w_var( inline_return_button.click() call_with_var_str_cast_wrapped_inline_button.click() expect(last_result).to_have_value("8") + + +def test_await_call_script(call_script: AppHarness, call_script_page: Page): + """A background handler awaits the value, error or timeout of a browser script. + + Args: + call_script: harness for CallScript app. + call_script_page: Playwright page. + """ + expected_lines = ( + "{'inline3': 42, 'a': [1, 2, 3], 's': 'js', 'o': {'a': 1, 'b': 2}}", + "'async inline4'", + "[1, 'two', None]", + "None", + "BrowserScriptError: ReferenceError: missing_function is not defined", + ( + "BrowserResultSerializationError: TypeError: The script returned a DOM " + "node or window, which JSON cannot carry; return the data you need from " + "it instead." + ), + ( + "TimeoutError: The browser did not return a result for `_call_script` " + "within 0.5 seconds." + ), + ) + call_script_page.locator("#await_results").click() + expect(call_script_page.locator("#awaited")).to_have_value( + "\n".join(expected_lines), timeout=15_000 + ) + + +def test_awaited_script_does_not_hold_up_other_events( + call_script: AppHarness, call_script_page: Page +): + """While an awaited script waits on the user, the tab's other events still run. + + Args: + call_script: harness for CallScript app. + call_script_page: Playwright page. + """ + call_script_page.locator("#await_user").click() + call_script_page.wait_for_function( + "() => typeof window.answerAwaited === 'function'" + ) + call_script_page.locator("#set_value_busy").click() + expect(call_script_page.locator("#value")).to_have_text("busy") + call_script_page.evaluate("window.answerAwaited({answer: 'yes'})") + expect(call_script_page.locator("#awaited")).to_have_value("{'answer': 'yes'}") diff --git a/tests/units/reflex_base/event/processor/test_base_state_processor.py b/tests/units/reflex_base/event/processor/test_base_state_processor.py index 0f6735439b6..8cae9e1c12a 100644 --- a/tests/units/reflex_base/event/processor/test_base_state_processor.py +++ b/tests/units/reflex_base/event/processor/test_base_state_processor.py @@ -5752,3 +5752,170 @@ def returns_plain(self): await future await processor.join(5) assert len(captured) == 1 + + +def _record_browser_calls( + processor: BaseStateEventProcessor, results: list[Any] +) -> list[tuple[str, str, dict[str, Any], float | None]]: + """Answer the processor's browser calls with the given results, in order. + + Args: + processor: The processor whose root context sends the calls. + results: The values the browser returns, one per call. + + Returns: + The calls made: token, event name, payload and timeout. + """ + calls: list[tuple[str, str, dict[str, Any], float | None]] = [] + + async def call_frontend_impl( # noqa: RUF029 + token: str, event: Event, timeout: float | None + ) -> Any: + calls.append((token, event.name, event.payload, timeout)) + return results[len(calls) - 1] + + assert processor._root_context is not None + processor._root_context = dataclasses.replace( + processor._root_context, call_frontend_impl=call_frontend_impl + ) + return calls + + +async def test_await_browser_call_from_background_returns_the_browser_result( + wired_app: App, + real_base_state_processor: BaseStateEventProcessor, + token: str, +): + """A background handler awaits a script's result; the timeout is not sent to the browser. + + Args: + wired_app: The App wired to the processor's state manager. + real_base_state_processor: The unmocked BaseStateEventProcessor. + token: The client token. + """ + calls = _record_browser_calls(real_base_state_processor, [2, {"w": 800}, None]) + results: list[Any] = [] + + class BrowserCallState(State): + @event(background=True) + async def run(self): + results.append(await rx.call_script("1 + 1")) + results.append(await rx.call_function("() => ({w: 800})", timeout=2)) + results.append(await rx.run_script("null", timeout=None)) + + async with real_base_state_processor as processor: + future = await processor.enqueue( + token, Event.from_event_type(BrowserCallState.run())[0] + ) + await future.wait_all() + + assert results == [2, {"w": 800}, None] + assert calls == [ + ( + token, + "_call_script", + {"javascript_code": "1 + 1", "callback": None}, + get_config().browser_call_timeout, + ), + ( + token, + "_call_function", + {"function": "() => ({w: 800})", "callback": None}, + 2, + ), + (token, "_call_function", {"function": "(() => null)", "callback": None}, None), + ] + + +async def test_await_browser_call_under_the_lock_or_with_a_callback_raises( + wired_app: App, + real_base_state_processor: BaseStateEventProcessor, + token: str, +): + """A browser call is not awaited while the lock is held, nor with a callback too. + + Args: + wired_app: The App wired to the processor's state manager. + real_base_state_processor: The unmocked BaseStateEventProcessor. + token: The client token. + """ + from reflex_base.utils.exceptions import EventHandlerTypeError + + calls = _record_browser_calls(real_base_state_processor, []) + errors: dict[str, str] = {} + lock_error = ( + "`_call_script` cannot be awaited while the state lock is held, as every " + "other event of this tab would wait for the browser's answer; await it in " + "a background event handler, outside `async with self`." + ) + + class LockedBrowserCallState(State): + @event + async def foreground(self): + try: + await rx.call_script("1") + except EventHandlerTypeError as ex: + errors["foreground"] = str(ex) + + @event(background=True) + async def background(self): + async with self: + try: + await rx.call_script("1") + except EventHandlerTypeError as ex: + errors["async with self"] = str(ex) + try: + await rx.call_function("() => 1", callback=rx.console_log) + except EventHandlerTypeError as ex: + errors["callback"] = str(ex) + + async with real_base_state_processor as processor: + for handler in ( + LockedBrowserCallState.foreground, + LockedBrowserCallState.background, + ): + future = await processor.enqueue(token, Event.from_event_type(handler())[0]) + await future.wait_all() + + assert errors == { + "foreground": lock_error, + "async with self": lock_error, + "callback": "`_call_function` was given a callback and awaited; pass " + "either callback= or await its result, not both.", + } + assert calls == [] + + +async def test_await_browser_call_without_a_frontend_raises( + wired_app: App, + real_base_state_processor: BaseStateEventProcessor, + token: str, +): + """With no frontend attached to the processor, a browser call fails at once. + + Args: + wired_app: The App wired to the processor's state manager. + real_base_state_processor: The unmocked BaseStateEventProcessor. + token: The client token. + """ + from reflex_base.utils.exceptions import BrowserDisconnectedError + + errors: list[str] = [] + + class NoFrontendState(State): + @event(background=True) + async def run(self): + try: + await rx.call_script("1") + except BrowserDisconnectedError as ex: + errors.append(str(ex)) + + async with real_base_state_processor as processor: + future = await processor.enqueue( + token, Event.from_event_type(NoFrontendState.run())[0] + ) + await future.wait_all() + + assert errors == [ + "No browser is connected to this app, so it cannot run the script." + ] diff --git a/tests/units/reflex_base/event/processor/test_browser_calls.py b/tests/units/reflex_base/event/processor/test_browser_calls.py new file mode 100644 index 00000000000..58a85521642 --- /dev/null +++ b/tests/units/reflex_base/event/processor/test_browser_calls.py @@ -0,0 +1,266 @@ +"""Tests for the registry of browser calls the backend awaits.""" + +import asyncio +from typing import Any + +import pytest +from reflex_base.event import Event +from reflex_base.event.processor.browser_calls import BrowserCalls +from reflex_base.utils.exceptions import ( + BrowserDisconnectedError, + BrowserResultSerializationError, + BrowserScriptError, +) + +EVENT = Event(name="_call_script", payload={"javascript_code": "1", "callback": None}) + + +class Browser: + """Records the events sent to it, like a connected tab.""" + + def __init__(self): + """Start with nothing sent.""" + self.sent: list[tuple[str, Event]] = [] + self.received = asyncio.Event() + + async def emit(self, token: str, event: Event) -> None: + """Record an event sent to a tab. + + Args: + token: The client token. + event: The event sent. + """ + self.sent.append((token, event)) + self.received.set() + + async def rid(self) -> str: + """Wait for the first event sent and return its request id. + + Returns: + The request id of the event. + """ + await self.received.wait() + rid = self.sent[0][1].rid + assert rid is not None + return rid + + +async def _start_call( + calls: BrowserCalls, timeout: float | None = None, token: str = "tok" +) -> tuple[Browser, asyncio.Task[Any], str]: + """Start a call and wait for its event to be sent. + + Args: + calls: The registry. + timeout: The call's timeout. + token: The client token. + + Returns: + The browser, the task awaiting the call, and the call's request id. + """ + browser = Browser() + task = asyncio.create_task(calls.call(token, EVENT, timeout, browser.emit)) + return browser, task, await browser.rid() + + +async def test_call_sends_the_event_with_a_request_id_and_returns_the_result(): + """The browser receives the event with a rid; its JSON result is the call's value.""" + calls = BrowserCalls() + browser, task, rid = await _start_call(calls) + assert browser.sent == [ + ( + "tok", + Event( + name="_call_script", + payload={"javascript_code": "1", "callback": None}, + rid=rid, + ), + ) + ] + calls.resolve("tok", rid, {"rid": rid, "json": '{"a": [1, null]}'}) + assert await task == {"a": [1, None]} + assert calls._pending == {} + + +async def test_a_result_from_another_token_or_request_is_ignored(): + """Only the tab a call was sent to can answer it, and only under its rid.""" + calls = BrowserCalls() + _, task, rid = await _start_call(calls) + calls.resolve("other", rid, {"json": "1"}) + calls.resolve("tok", "unknown", {"json": "2"}) + await asyncio.sleep(0) + assert not task.done() + calls.resolve("tok", rid, {"json": "3"}) + assert await task == 3 + # A late duplicate after the call settled is dropped. + calls.resolve("tok", rid, {"json": "4"}) + + +@pytest.mark.parametrize( + ("error", "expected_type", "expected"), + [ + ( + {"name": "TypeError", "message": "x is undefined", "stack": "at "}, + BrowserScriptError, + ("TypeError", "x is undefined", "at ", "TypeError: x is undefined"), + ), + ( + { + "name": "TypeError", + "message": "Do not know how to serialize a BigInt", + "stack": "", + "kind": "serialization", + }, + BrowserResultSerializationError, + ( + "TypeError", + "Do not know how to serialize a BigInt", + "", + "TypeError: Do not know how to serialize a BigInt", + ), + ), + ( + {}, + BrowserScriptError, + ("Error", "", "", "Error: "), + ), + ], +) +async def test_an_error_the_browser_reports_is_raised( + error: dict[str, str], + expected_type: type[BrowserScriptError], + expected: tuple[str, str, str, str], +): + """A script error raises BrowserScriptError; a value JSON cannot carry, its subclass. + + Args: + error: The error the browser reports. + expected_type: The exception type the call raises. + expected: The exception's name, message, stack and str. + """ + calls = BrowserCalls() + _, task, rid = await _start_call(calls) + calls.resolve("tok", rid, {"rid": rid, "error": error}) + with pytest.raises(expected_type) as exc_info: + await task + exc = exc_info.value + assert type(exc) is expected_type + assert (exc.name, exc.message, exc.stack, str(exc)) == expected + + +@pytest.mark.parametrize( + ("outcome", "expected"), + [ + ({}, "KeyError: The browser sent a malformed result: 'json'"), + ( + {"json": "{"}, + ( + "JSONDecodeError: The browser sent a malformed result: Expecting " + "property name enclosed in double quotes: line 1 column 2 (char 1)" + ), + ), + ( + {"json": 5}, + ( + "TypeError: The browser sent a malformed result: the JSON object " + "must be str, bytes or bytearray, not int" + ), + ), + ], +) +async def test_a_malformed_result_raises_a_serialization_error( + outcome: dict[str, Any], expected: str +): + """A result without valid JSON fails the call instead of hanging it. + + Args: + outcome: The malformed outcome. + expected: The error's message. + """ + calls = BrowserCalls() + _, task, rid = await _start_call(calls) + calls.resolve("tok", rid, outcome) + with pytest.raises(BrowserResultSerializationError) as exc_info: + await task + assert str(exc_info.value) == expected + + +async def test_call_times_out(): + """A call without a result within its timeout raises TimeoutError and is forgotten.""" + calls = BrowserCalls() + with pytest.raises(TimeoutError) as exc_info: + await calls.call("tok", EVENT, 0.01, Browser().emit) + assert str(exc_info.value) == ( + "The browser did not return a result for `_call_script` within 0.01 seconds." + ) + assert calls._pending == {} + + +async def test_disconnect_fails_the_calls_after_the_grace_period(): + """A tab that does not reconnect within the grace period fails its calls.""" + calls = BrowserCalls() + _, task, _ = await _start_call(calls) + calls.disconnect("tok", 0.01) + with pytest.raises(BrowserDisconnectedError) as exc_info: + await task + assert str(exc_info.value) == ( + "The browser tab disconnected before returning a result." + ) + assert calls._pending == {} + assert calls._grace_timers == {} + + +async def test_disconnect_without_a_grace_period_fails_the_calls_at_once(): + """A grace period of zero fails the calls on the disconnect itself.""" + calls = BrowserCalls() + _, task, _ = await _start_call(calls) + calls.disconnect("tok", 0) + assert calls._grace_timers == {} + with pytest.raises(BrowserDisconnectedError): + await task + + +async def test_reconnect_within_the_grace_period_keeps_the_calls(): + """A tab reconnecting in time still answers its calls.""" + calls = BrowserCalls() + _, task, rid = await _start_call(calls) + calls.disconnect("tok", 0.01) + calls.reconnect("tok") + assert calls._grace_timers == {} + await asyncio.sleep(0.02) + assert not task.done() + calls.resolve("tok", rid, {"json": "true"}) + assert await task is True + + +def test_disconnect_without_pending_calls_starts_no_timer(): + """A tab with nothing pending needs no grace period.""" + calls = BrowserCalls() + calls.disconnect("tok", 5) + assert calls._grace_timers == {} + + +async def test_settled_call_ends_the_grace_period(): + """The last call settling during the grace period cancels its timer.""" + calls = BrowserCalls() + _, task, rid = await _start_call(calls) + calls.disconnect("tok", 5) + timer = calls._grace_timers["tok"] + calls.resolve("tok", rid, {"json": "1"}) + assert await task == 1 + assert calls._grace_timers == {} + assert timer.cancelled() + + +async def test_close_cancels_pending_calls(): + """Shutting the backend down cancels the calls still waiting.""" + calls = BrowserCalls() + _, task, _ = await _start_call(calls) + calls.disconnect("tok", 5) + timer = calls._grace_timers["tok"] + calls.close() + with pytest.raises(asyncio.CancelledError): + await task + assert timer.cancelled() + assert calls._pending == {} + assert calls._grace_timers == {} diff --git a/tests/units/reflex_base/event/processor/test_event_processor.py b/tests/units/reflex_base/event/processor/test_event_processor.py index 7302bbeb6d2..af8e6d0331b 100644 --- a/tests/units/reflex_base/event/processor/test_event_processor.py +++ b/tests/units/reflex_base/event/processor/test_event_processor.py @@ -2164,3 +2164,102 @@ def _returns_future() -> asyncio.Future[int]: async with mock_event_processor as ep: event_future = await ep.enqueue(token, Event.from_event_type(future_event())[0]) assert await event_future == 11 + + +class _FakeEventNamespace: + """Records the updates sent to the clients it reports as connected.""" + + def __init__(self, *connected: str): + """Connect the given tokens. + + Args: + connected: The connected client tokens. + """ + self.connected = set(connected) + self.updates: list[tuple[str, Any]] = [] + self.sent = asyncio.Event() + + def _is_connected(self, token: str) -> bool: + """Whether a client is connected. + + Args: + token: The client token. + + Returns: + Whether the token is connected. + """ + return token in self.connected + + async def emit_update(self, update: Any, token: str) -> None: + """Record an update sent to a client. + + Args: + update: The state update. + token: The client token. + """ + self.updates.append((token, update)) + self.sent.set() + + async def next_rid(self) -> str: + """Wait for the next update and return the request id of its event. + + Returns: + The request id the event was sent with. + """ + await self.sent.wait() + self.sent.clear() + rid = self.updates[-1][1].events[0].rid + assert rid is not None + return rid + + +async def test_call_frontend_sends_the_event_and_awaits_its_result( + processor: EventProcessor, +): + """The configured call_frontend sends the event with a rid and resolves with the result. + + Calls to a tab that is not connected fail at once; a tab disconnecting + fails its calls after the grace period unless it reconnects; stopping + the processor cancels the calls still waiting. + + Args: + processor: The event processor fixture. + """ + from reflex_base.utils.exceptions import BrowserDisconnectedError + + event = Event(name="_call_script", payload={"javascript_code": "1"}) + namespace = _FakeEventNamespace("tok") + processor.browser_call_grace_period = 0.01 + processor.configure(event_namespace=namespace) # pyright: ignore[reportArgumentType] + assert processor._root_context is not None + ctx = processor._root_context.fork(token="tok") + + async with processor: + with pytest.raises(BrowserDisconnectedError) as exc_info: + await processor._root_context.fork(token="gone").call_frontend(event, 1) + assert str(exc_info.value) == ( + "The browser tab is not connected, so `_call_script` cannot run in it." + ) + + answered = asyncio.create_task(ctx.call_frontend(event, 1)) + rid = await namespace.next_rid() + assert [(token, update.events) for token, update in namespace.updates] == [ + ("tok", [dataclasses.replace(event, rid=rid)]) + ] + # Reconnecting within the grace period keeps the call. + processor._on_disconnect("tok") + processor._on_connect("tok") + await asyncio.sleep(0.02) + processor._browser_calls.resolve("tok", rid, {"json": "[1]"}) + assert await answered == [1] + + abandoned = asyncio.create_task(ctx.call_frontend(event, 1)) + await namespace.next_rid() + processor._on_disconnect("tok") + with pytest.raises(BrowserDisconnectedError): + await abandoned + + pending = asyncio.create_task(ctx.call_frontend(event, None)) + await namespace.next_rid() + with pytest.raises(asyncio.CancelledError): + await pending diff --git a/tests/units/reflex_base/event/test_init.py b/tests/units/reflex_base/event/test_init.py index fc4869d245b..aa11fe1382e 100644 --- a/tests/units/reflex_base/event/test_init.py +++ b/tests/units/reflex_base/event/test_init.py @@ -4,6 +4,7 @@ from reflex_base.client_state import client_state from reflex_base.event import ( + Event, EventArgVar, EventChain, LambdaEventCallback, @@ -13,6 +14,7 @@ parse_args_spec, passthrough_event_spec, ) +from reflex_base.utils.format import json_dumps from reflex_base.vars.base import Var from reflex_base.vars.number import NumberVar @@ -98,3 +100,33 @@ def test_cond_between_function_and_none_inside_lambda_is_a_no_op_when_false() -> str(chain) == '((_ev_0) => (((_ev_0?.valueOf?.() === "go"?.valueOf?.()) ? ((_ev_0) => (flagRxClientStateSet(_ev_0))) : null)?.(_ev_0)))' ) + + +def test_event_is_serialized_with_a_request_id_only_when_awaited(): + """An event nobody awaits is sent as it always was; an awaited one carries its rid.""" + event = Event(name="_call_script", payload={"javascript_code": "1"}) + assert json_dumps(event) == ( + '{"name": "_call_script", "router_data": {}, ' + '"payload": {"javascript_code": "1"}}' + ) + assert json_dumps(Event(name="_call_script", rid="r1")) == ( + '{"name": "_call_script", "router_data": {}, "payload": {}, "rid": "r1"}' + ) + + +def test_script_events_carry_a_timeout_only_when_given(): + """A timeout passed to a script event is in its payload; an unset one is not.""" + assert [ + spec._to_event().payload + for spec in ( + rx.call_script("1"), + rx.call_script("1", timeout=5), + rx.call_function("() => 1", timeout=None), + rx.run_script("2", timeout=1.5), + ) + ] == [ + {"javascript_code": "1", "callback": None}, + {"javascript_code": "1", "callback": None, "timeout": 5}, + {"function": "() => 1", "callback": None, "timeout": None}, + {"function": "(() => 2)", "callback": None, "timeout": 1.5}, + ] diff --git a/tests/units/test_app.py b/tests/units/test_app.py index b348f5f4eac..e7bac86398a 100644 --- a/tests/units/test_app.py +++ b/tests/units/test_app.py @@ -5651,6 +5651,103 @@ async def test_on_event_uses_connect_time_router_data( assert "sid1" not in event_namespace._static_router_data +def test_result_event_matches_handler_and_frontend(): + """The result socket event reaches on_result, under the name state.js emits.""" + assert f"on_{constants.SocketEvent.RESULT}" == EventNamespace.on_result.__name__ + state_js = (Templates.Dirs.WEB_TEMPLATE / "utils/state.js").read_text() + (frontend_name,) = re.findall( + r'^const RESULT_EVENT = "(.*)";$', state_js, re.MULTILINE + ) + assert frontend_name == constants.SocketEvent.RESULT + + +@pytest.mark.asyncio +async def test_on_result_settles_the_call_of_the_sending_token( + event_namespace_with_processor_mock: EventNamespace, +): + """A result resolves the sending tab's call; a malformed or unknown one is dropped. + + Args: + event_namespace_with_processor_mock: Namespace with a mocked processor. + """ + namespace = event_namespace_with_processor_mock + namespace._token_manager.sid_to_token["sid1"] = "token" + resolve = cast(Mock, namespace.app.event_processor._browser_calls.resolve) + outcome = {"rid": "r1", "json": "1"} + await namespace.on_result("sid1", outcome) + resolve.assert_called_once_with("token", "r1", outcome) + + resolve.reset_mock() + await namespace.on_result("unknown-sid", outcome) + await namespace.on_result("sid1") + await namespace.on_result("sid1", ["r1"]) + await namespace.on_result("sid1", {"rid": 1, "json": "1"}) + resolve.assert_not_called() + + +def test_is_connected_only_for_a_socket_on_this_instance( + event_namespace_with_processor_mock: EventNamespace, +): + """Browser calls go only to a tab whose socket is connected to this instance. + + Args: + event_namespace_with_processor_mock: Namespace with a mocked processor. + """ + namespace = event_namespace_with_processor_mock + manager = namespace._token_manager + manager.token_to_socket["local"] = SocketRecord( + instance_id=manager.instance_id, sid="sid1" + ) + manager.token_to_socket["remote"] = SocketRecord(instance_id="other", sid="sid2") + assert [ + namespace._is_connected(token) for token in ("local", "remote", "missing") + ] == [True, False, False] + + +@pytest.mark.asyncio +@pytest.mark.parametrize("duplicate", [False, True]) +async def test_link_token_to_sid_ends_the_grace_period_of_a_reconnecting_tab( + event_namespace_with_processor_mock: EventNamespace, + duplicate: bool, +): + """A tab reconnecting under its token keeps its browser calls; a new tab does not. + + Args: + event_namespace_with_processor_mock: Namespace with a mocked processor. + duplicate: Whether the token is a duplicate, so the tab gets a new one. + """ + namespace = event_namespace_with_processor_mock + namespace._token_manager.link_token_to_sid = AsyncMock( + return_value="new-token" if duplicate else None + ) + namespace.emit = AsyncMock() + await namespace.link_token_to_sid("sid1", "token", update_state=False) + on_connect = cast(Mock, namespace.app.event_processor._on_connect) + if duplicate: + on_connect.assert_not_called() + else: + on_connect.assert_called_once_with("token") + + +@pytest.mark.asyncio +async def test_on_event_ignores_a_request_id_the_client_sends( + token: str, + event_namespace_with_processor_mock: EventNamespace, +): + """Only the backend sets an event's rid: a client cannot send one. + + Args: + token: A token. + event_namespace_with_processor_mock: Namespace with a mocked processor. + """ + namespace = event_namespace_with_processor_mock + await namespace.on_connect("sid1", _connect_environ(token)) + await namespace.on_event("sid1", {**_client_event_payload(), "rid": "r1"}) + enqueue_mock = cast(AsyncMock, namespace.app.event_processor.enqueue) + enqueue_mock.assert_called_once() + assert enqueue_mock.call_args[0][1].rid is None + + @pytest.mark.asyncio async def test_link_token_to_sid_records_the_connecting_identity( token: str, From e285c291ff088e6df8113501c832a384b6aa0482 Mon Sep 17 00:00:00 2001 From: Farhan Date: Sat, 21 Nov 2026 13:20:22 +0000 Subject: [PATCH 02/13] Keep timeout out of script event signatures add_args binds extra arguments to the event's signature parameters, so the new keyword-only timeout absorbed one. The signature the event reports now leaves it out. runEventScript declares the late-bound addEvents alias itself, as every function that runs user code must. Claude-Session: https://claude.ai/code/session_01LwJUCVxPh3ihrnaFn6CWnf --- .../src/reflex_base/event/__init__.py | 21 +++++++++++++++++-- packages/reflex-frontend/src/utils/state.js | 15 ++++++++----- 2 files changed, 29 insertions(+), 7 deletions(-) diff --git a/packages/reflex-base/src/reflex_base/event/__init__.py b/packages/reflex-base/src/reflex_base/event/__init__.py index f0ec7a806ff..cb8d860c3e6 100644 --- a/packages/reflex-base/src/reflex_base/event/__init__.py +++ b/packages/reflex-base/src/reflex_base/event/__init__.py @@ -2114,6 +2114,23 @@ def download( ) +def _script_signature(fn: Callable) -> inspect.Signature: + """Get the signature of a script event, without the timeout of an awaited call. + + The timeout is not an argument of the event: ``add_args`` must not bind to it. + + Args: + fn: The function creating the script event. + + Returns: + The function's signature without its ``timeout`` parameter. + """ + sig = inspect.signature(fn) + return sig.replace( + parameters=[p for name, p in sig.parameters.items() if name != "timeout"] + ) + + def _script_kwargs( callback: "EventType[Any] | None", timeout: float | Unset | None ) -> dict[str, Any]: @@ -2170,7 +2187,7 @@ def call_script( return server_side( "_call_script", - inspect.signature(call_script), + _script_signature(call_script), javascript_code=javascript_code, **_script_kwargs(callback, timeout), ) @@ -2202,7 +2219,7 @@ def call_function( return server_side( "_call_function", - inspect.signature(call_function), + _script_signature(call_function), function=javascript_code, **_script_kwargs(callback, timeout), ) diff --git a/packages/reflex-frontend/src/utils/state.js b/packages/reflex-frontend/src/utils/state.js index 4b5f7c706b9..a57d69c3b7c 100644 --- a/packages/reflex-frontend/src/utils/state.js +++ b/packages/reflex-frontend/src/utils/state.js @@ -599,13 +599,15 @@ const applyResultCallback = async ( /** * Run the script of a _call_script or _call_function event. * @param event The event whose script to run. - * @param addEvents The late-bound event dispatcher for the script. * @param socket The socket object to send events on. * @param navigate The navigate function from useNavigate. * @param params The params object from useParams. * @returns The script's completion value, or the function's return value. */ -const runEventScript = (event, addEvents, socket, navigate, params) => { +const runEventScript = (event, socket, navigate, params) => { + // User code dispatches through addEvents like compiled event triggers do; + // late-bound so a remounted EventLoopProvider is picked up. + const addEvents = (...args) => eventLoop.addEvents(...args); if (event.name === "_call_script") { return runScript( event.payload.javascript_code, @@ -679,7 +681,10 @@ const sendScriptResult = async (socket, rid, run) => { try { outcome = { rid, json: serializeScriptResult(value) }; } catch (e) { - outcome = { rid, error: describeScriptError(e, SERIALIZATION_ERROR_KIND) }; + outcome = { + rid, + error: describeScriptError(e, SERIALIZATION_ERROR_KIND), + }; } } catch (e) { outcome = { rid, error: describeScriptError(e) }; @@ -903,14 +908,14 @@ export const applyEvent = async (event, socket, navigate, params) => { if (event.rid) { // The backend awaits the result: an error is its to handle. void sendScriptResult(socket, event.rid, () => - runEventScript(event, addEvents, socket, navigate, params), + runEventScript(event, socket, navigate, params), ); return; } try { await applyResultCallback( event, - runEventScript(event, addEvents, socket, navigate, params), + runEventScript(event, socket, navigate, params), socket, navigate, params, From 42ba65cb08fb853bad425b82fc2faab8a2d29dc5 Mon Sep 17 00:00:00 2001 From: Farhan Date: Sat, 21 Nov 2026 13:24:28 +0000 Subject: [PATCH 03/13] Format the awaited script result tests Claude-Session: https://claude.ai/code/session_01LwJUCVxPh3ihrnaFn6CWnf --- packages/reflex-frontend/tests/run_script.test.js | 7 +------ 1 file changed, 1 insertion(+), 6 deletions(-) diff --git a/packages/reflex-frontend/tests/run_script.test.js b/packages/reflex-frontend/tests/run_script.test.js index 7691b7f9dc7..ded8a1cb736 100644 --- a/packages/reflex-frontend/tests/run_script.test.js +++ b/packages/reflex-frontend/tests/run_script.test.js @@ -240,12 +240,7 @@ describe("awaited script results", () => { "TypeError", "The script returned a function, which JSON cannot carry.", ], - [ - "a BigInt", - "1n", - "TypeError", - "Do not know how to serialize a BigInt", - ], + ["a BigInt", "1n", "TypeError", "Do not know how to serialize a BigInt"], ])("rejects %s as a serialization error", async (_what, code, name, message) => { const { outcome } = awaited(script(code)); expect(withoutStack(await outcome())).toEqual({ From 154a89468766f5494c707cfbdcb34eb634305d8d Mon Sep 17 00:00:00 2001 From: Farhan Date: Sat, 21 Nov 2026 13:25:43 +0000 Subject: [PATCH 04/13] Report script errors whose value cannot become text String() throws on an object without a prototype, so a script rejecting with one sent no result and its call waited for the timeout. Error fields now fall back to Object.prototype.toString. The new tests also import the exceptions at the top of their modules. Claude-Session: https://claude.ai/code/session_01LwJUCVxPh3ihrnaFn6CWnf --- packages/reflex-frontend/src/utils/state.js | 19 ++++++++++++++++--- .../reflex-frontend/tests/run_script.test.js | 10 ++++++++++ .../processor/test_base_state_processor.py | 5 +---- .../event/processor/test_event_processor.py | 3 +-- 4 files changed, 28 insertions(+), 9 deletions(-) diff --git a/packages/reflex-frontend/src/utils/state.js b/packages/reflex-frontend/src/utils/state.js index a57d69c3b7c..c6272e24c0d 100644 --- a/packages/reflex-frontend/src/utils/state.js +++ b/packages/reflex-frontend/src/utils/state.js @@ -624,6 +624,19 @@ const runEventScript = (event, socket, navigate, params) => { return fn(); }; +/** + * Convert a value a script threw to text, which String() cannot always do. + * @param value The value to convert. + * @returns The value as text; an object without a prototype is "[object Object]". + */ +const toText = (value) => { + try { + return String(value); + } catch { + return Object.prototype.toString.call(value); + } +}; + /** * Describe an error a script threw, for the backend that awaits its result. * @param error The thrown value, which need not be an Error. @@ -631,9 +644,9 @@ const runEventScript = (event, socket, navigate, params) => { * @returns The error's name, message and stack. */ const describeScriptError = (error, kind = undefined) => ({ - name: error?.name ?? "Error", - message: error instanceof Error ? error.message : String(error), - stack: error?.stack ?? "", + name: toText(error?.name ?? "Error"), + message: toText(error instanceof Error ? error.message : error), + stack: toText(error?.stack ?? ""), ...(kind === undefined ? {} : { kind }), }); diff --git a/packages/reflex-frontend/tests/run_script.test.js b/packages/reflex-frontend/tests/run_script.test.js index ded8a1cb736..7857e39fb4b 100644 --- a/packages/reflex-frontend/tests/run_script.test.js +++ b/packages/reflex-frontend/tests/run_script.test.js @@ -215,6 +215,16 @@ describe("awaited script results", () => { }); }); + test("describes a thrown value that cannot become a string", async () => { + // String() throws on an object without a prototype; the backend must + // still receive an error rather than wait for its timeout. + const { outcome } = awaited(script("Promise.reject(Object.create(null))")); + expect(await outcome()).toEqual({ + rid: "r1", + error: { name: "Error", message: "[object Object]", stack: "" }, + }); + }); + test.each([ [ "a DOM node", diff --git a/tests/units/reflex_base/event/processor/test_base_state_processor.py b/tests/units/reflex_base/event/processor/test_base_state_processor.py index 8cae9e1c12a..a48409bf903 100644 --- a/tests/units/reflex_base/event/processor/test_base_state_processor.py +++ b/tests/units/reflex_base/event/processor/test_base_state_processor.py @@ -37,6 +37,7 @@ _transform_event_payload, ) from reflex_base.registry import RegistrationContext +from reflex_base.utils.exceptions import BrowserDisconnectedError, EventHandlerTypeError from reflex_base.utils.form import FORM_DATA_ENTRIES_KEY, FormData from reflex_base.utils.types import Receive, Scope, Send @@ -5839,8 +5840,6 @@ async def test_await_browser_call_under_the_lock_or_with_a_callback_raises( real_base_state_processor: The unmocked BaseStateEventProcessor. token: The client token. """ - from reflex_base.utils.exceptions import EventHandlerTypeError - calls = _record_browser_calls(real_base_state_processor, []) errors: dict[str, str] = {} lock_error = ( @@ -5898,8 +5897,6 @@ async def test_await_browser_call_without_a_frontend_raises( real_base_state_processor: The unmocked BaseStateEventProcessor. token: The client token. """ - from reflex_base.utils.exceptions import BrowserDisconnectedError - errors: list[str] = [] class NoFrontendState(State): diff --git a/tests/units/reflex_base/event/processor/test_event_processor.py b/tests/units/reflex_base/event/processor/test_event_processor.py index af8e6d0331b..48a4779a03e 100644 --- a/tests/units/reflex_base/event/processor/test_event_processor.py +++ b/tests/units/reflex_base/event/processor/test_event_processor.py @@ -27,6 +27,7 @@ ) from reflex_base.event.processor.future import EventFuture from reflex_base.registry import RegistrationContext +from reflex_base.utils.exceptions import BrowserDisconnectedError from reflex.event import Event, EventHandler, EventSpec from tests.units.conftest import active_tracer @@ -2225,8 +2226,6 @@ async def test_call_frontend_sends_the_event_and_awaits_its_result( Args: processor: The event processor fixture. """ - from reflex_base.utils.exceptions import BrowserDisconnectedError - event = Event(name="_call_script", payload={"javascript_code": "1"}) namespace = _FakeEventNamespace("tok") processor.browser_call_grace_period = 0.01 From b33c046331dc0e3d6f3b2499725f7ce66a73e61c Mon Sep 17 00:00:00 2001 From: Farhan Date: Sat, 21 Nov 2026 13:30:52 +0000 Subject: [PATCH 05/13] Carry the browser call request id in the script event's payload The rid field on Event cost every Event one more frozen field write (CodSpeed: -7% on from_event_type). Only _call_script and _call_function ever carry a request id, so it now goes in their payload and no other event pays for it; the Event serializer and the _EVENT_FIELDS change are gone with the field. The script event signature is also computed once instead of on every call, which made console_log 8% slower. Claude-Session: https://claude.ai/code/session_01LwJUCVxPh3ihrnaFn6CWnf --- .../src/reflex_base/event/__init__.py | 34 ++----------------- .../event/processor/browser_calls.py | 10 +++++- packages/reflex-frontend/src/utils/state.js | 4 +-- .../reflex-frontend/tests/run_script.test.js | 7 +++- reflex/app.py | 3 +- .../event/processor/test_browser_calls.py | 9 ++--- .../event/processor/test_event_processor.py | 6 ++-- tests/units/reflex_base/event/test_init.py | 14 -------- tests/units/test_app.py | 19 ----------- 9 files changed, 26 insertions(+), 80 deletions(-) diff --git a/packages/reflex-base/src/reflex_base/event/__init__.py b/packages/reflex-base/src/reflex_base/event/__init__.py index cb8d860c3e6..2e1f3b826f3 100644 --- a/packages/reflex-base/src/reflex_base/event/__init__.py +++ b/packages/reflex-base/src/reflex_base/event/__init__.py @@ -47,7 +47,6 @@ EventHandlerArgTypeMismatchError, MissingAnnotationError, ) -from reflex_base.utils.serializers import serializer from reflex_base.utils.types import ( ArgsSpec, GenericType, @@ -101,8 +100,6 @@ class Event: name: The event name. router_data: The routing data where event occurred. payload: The event payload. - rid: Correlates a frontend event with the result the browser sends - back, set only when the backend awaits that result. """ name: str @@ -111,8 +108,6 @@ class Event: payload: dict[str, Any] = dataclasses.field(default_factory=dict) - rid: str | None = None - @property def state_cls(self) -> "type[BaseState]": """The state class for the event.""" @@ -165,33 +160,7 @@ def from_event_type( return out -# The fields a client may set on an event it sends. -_EVENT_FIELDS: set[str] = {"name", "router_data", "payload"} - - -@serializer(to=dict) -def serialize_event(event: Event) -> dict[str, Any]: - """Serialize an event sent to the frontend. - - ``rid`` is included only when set, so an event nobody awaits is sent as - it always was. - - Args: - event: The event. - - Returns: - The serialized event. - """ - serialized = { - "name": event.name, - "router_data": event.router_data, - "payload": event.payload, - } - if event.rid is not None: - serialized["rid"] = event.rid - return serialized - - +_EVENT_FIELDS: set[str] = {f.name for f in dataclasses.fields(Event)} _EMPTY_EVENTS = LiteralVar.create([]) _EMPTY_EVENT_ACTIONS = LiteralVar.create({}) @@ -2114,6 +2083,7 @@ def download( ) +@lru_cache def _script_signature(fn: Callable) -> inspect.Signature: """Get the signature of a script event, without the timeout of an awaited call. diff --git a/packages/reflex-base/src/reflex_base/event/processor/browser_calls.py b/packages/reflex-base/src/reflex_base/event/processor/browser_calls.py index 6dd08dfd39a..e4f354d1d59 100644 --- a/packages/reflex-base/src/reflex_base/event/processor/browser_calls.py +++ b/packages/reflex-base/src/reflex_base/event/processor/browser_calls.py @@ -21,6 +21,9 @@ # The ``kind`` of the error the frontend reports for a value JSON cannot carry. SERIALIZATION_ERROR_KIND = "serialization" +# The payload key of a browser call's request id (must match state.js). +RID_KEY = "rid" + @dataclasses.dataclass(slots=True) class BrowserCalls: @@ -66,7 +69,12 @@ async def call( calls = self._pending.setdefault(token, {}) calls[rid] = future try: - await emit(token, dataclasses.replace(event, rid=rid)) + # Only the browser-call events carry a request id, in their + # payload, so no other event pays for it. + await emit( + token, + dataclasses.replace(event, payload={**event.payload, RID_KEY: rid}), + ) try: return await asyncio.wait_for(future, timeout) except TimeoutError: diff --git a/packages/reflex-frontend/src/utils/state.js b/packages/reflex-frontend/src/utils/state.js index c6272e24c0d..4eca746405c 100644 --- a/packages/reflex-frontend/src/utils/state.js +++ b/packages/reflex-frontend/src/utils/state.js @@ -918,9 +918,9 @@ export const applyEvent = async (event, socket, navigate, params) => { } if (event.name === "_call_script" || event.name === "_call_function") { - if (event.rid) { + if (event.payload.rid) { // The backend awaits the result: an error is its to handle. - void sendScriptResult(socket, event.rid, () => + void sendScriptResult(socket, event.payload.rid, () => runEventScript(event, socket, navigate, params), ); return; diff --git a/packages/reflex-frontend/tests/run_script.test.js b/packages/reflex-frontend/tests/run_script.test.js index 7857e39fb4b..536b08f22a0 100644 --- a/packages/reflex-frontend/tests/run_script.test.js +++ b/packages/reflex-frontend/tests/run_script.test.js @@ -126,7 +126,12 @@ describe("awaited script results", () => { const socket = { emit: vi.fn() }; return { socket, - applied: applyEvent({ ...event, rid: "r1" }, socket, null, null), + applied: applyEvent( + { ...event, payload: { ...event.payload, rid: "r1" } }, + socket, + null, + null, + ), // The outcome the backend receives, once the script has settled. outcome: async () => { await vi.waitFor(() => expect(socket.emit).toHaveBeenCalledTimes(1)); diff --git a/reflex/app.py b/reflex/app.py index 367190cdaac..a53e42c5f61 100644 --- a/reflex/app.py +++ b/reflex/app.py @@ -52,6 +52,7 @@ ) from reflex_base.event.context import EventContext from reflex_base.event.processor import BaseStateEventProcessor, EventProcessor +from reflex_base.event.processor.browser_calls import RID_KEY from reflex_base.registry import RegistrationContext from reflex_base.telemetry_context import CompileTrigger, TelemetryContext from reflex_base.utils import memo_paths @@ -3134,7 +3135,7 @@ async def on_result(self, sid: str, data: Any = None): data: ``{"rid": , "json": }``, or ``{"rid": , "error": {...}}`` when the script failed. """ - if not isinstance(data, dict) or not isinstance(rid := data.get("rid"), str): + if not isinstance(data, dict) or not isinstance(rid := data.get(RID_KEY), str): logger.debug(f"Ignoring malformed result payload from SID {sid}.") return if (token := self.sid_to_token.get(sid)) is None or ( diff --git a/tests/units/reflex_base/event/processor/test_browser_calls.py b/tests/units/reflex_base/event/processor/test_browser_calls.py index 58a85521642..49348ba4290 100644 --- a/tests/units/reflex_base/event/processor/test_browser_calls.py +++ b/tests/units/reflex_base/event/processor/test_browser_calls.py @@ -40,9 +40,7 @@ async def rid(self) -> str: The request id of the event. """ await self.received.wait() - rid = self.sent[0][1].rid - assert rid is not None - return rid + return self.sent[0][1].payload["rid"] async def _start_call( @@ -64,7 +62,7 @@ async def _start_call( async def test_call_sends_the_event_with_a_request_id_and_returns_the_result(): - """The browser receives the event with a rid; its JSON result is the call's value.""" + """The browser receives the event with a rid in its payload; its JSON result is the call's value.""" calls = BrowserCalls() browser, task, rid = await _start_call(calls) assert browser.sent == [ @@ -72,8 +70,7 @@ async def test_call_sends_the_event_with_a_request_id_and_returns_the_result(): "tok", Event( name="_call_script", - payload={"javascript_code": "1", "callback": None}, - rid=rid, + payload={"javascript_code": "1", "callback": None, "rid": rid}, ), ) ] diff --git a/tests/units/reflex_base/event/processor/test_event_processor.py b/tests/units/reflex_base/event/processor/test_event_processor.py index 48a4779a03e..d811eed7b2f 100644 --- a/tests/units/reflex_base/event/processor/test_event_processor.py +++ b/tests/units/reflex_base/event/processor/test_event_processor.py @@ -2209,9 +2209,7 @@ async def next_rid(self) -> str: """ await self.sent.wait() self.sent.clear() - rid = self.updates[-1][1].events[0].rid - assert rid is not None - return rid + return self.updates[-1][1].events[0].payload["rid"] async def test_call_frontend_sends_the_event_and_awaits_its_result( @@ -2243,7 +2241,7 @@ async def test_call_frontend_sends_the_event_and_awaits_its_result( answered = asyncio.create_task(ctx.call_frontend(event, 1)) rid = await namespace.next_rid() assert [(token, update.events) for token, update in namespace.updates] == [ - ("tok", [dataclasses.replace(event, rid=rid)]) + ("tok", [dataclasses.replace(event, payload={**event.payload, "rid": rid})]) ] # Reconnecting within the grace period keeps the call. processor._on_disconnect("tok") diff --git a/tests/units/reflex_base/event/test_init.py b/tests/units/reflex_base/event/test_init.py index aa11fe1382e..1422f3949ba 100644 --- a/tests/units/reflex_base/event/test_init.py +++ b/tests/units/reflex_base/event/test_init.py @@ -4,7 +4,6 @@ from reflex_base.client_state import client_state from reflex_base.event import ( - Event, EventArgVar, EventChain, LambdaEventCallback, @@ -14,7 +13,6 @@ parse_args_spec, passthrough_event_spec, ) -from reflex_base.utils.format import json_dumps from reflex_base.vars.base import Var from reflex_base.vars.number import NumberVar @@ -102,18 +100,6 @@ def test_cond_between_function_and_none_inside_lambda_is_a_no_op_when_false() -> ) -def test_event_is_serialized_with_a_request_id_only_when_awaited(): - """An event nobody awaits is sent as it always was; an awaited one carries its rid.""" - event = Event(name="_call_script", payload={"javascript_code": "1"}) - assert json_dumps(event) == ( - '{"name": "_call_script", "router_data": {}, ' - '"payload": {"javascript_code": "1"}}' - ) - assert json_dumps(Event(name="_call_script", rid="r1")) == ( - '{"name": "_call_script", "router_data": {}, "payload": {}, "rid": "r1"}' - ) - - def test_script_events_carry_a_timeout_only_when_given(): """A timeout passed to a script event is in its payload; an unset one is not.""" assert [ diff --git a/tests/units/test_app.py b/tests/units/test_app.py index e7bac86398a..463dc8d157e 100644 --- a/tests/units/test_app.py +++ b/tests/units/test_app.py @@ -5729,25 +5729,6 @@ async def test_link_token_to_sid_ends_the_grace_period_of_a_reconnecting_tab( on_connect.assert_called_once_with("token") -@pytest.mark.asyncio -async def test_on_event_ignores_a_request_id_the_client_sends( - token: str, - event_namespace_with_processor_mock: EventNamespace, -): - """Only the backend sets an event's rid: a client cannot send one. - - Args: - token: A token. - event_namespace_with_processor_mock: Namespace with a mocked processor. - """ - namespace = event_namespace_with_processor_mock - await namespace.on_connect("sid1", _connect_environ(token)) - await namespace.on_event("sid1", {**_client_event_payload(), "rid": "r1"}) - enqueue_mock = cast(AsyncMock, namespace.app.event_processor.enqueue) - enqueue_mock.assert_called_once() - assert enqueue_mock.call_args[0][1].rid is None - - @pytest.mark.asyncio async def test_link_token_to_sid_records_the_connecting_identity( token: str, From 53e44245af0ea730446e2aef9ce4e03aac181f5f Mon Sep 17 00:00:00 2001 From: Farhan Date: Sat, 21 Nov 2026 13:34:28 +0000 Subject: [PATCH 06/13] Import the exceptions at the top of the CallScript test app Claude-Session: https://claude.ai/code/session_01LwJUCVxPh3ihrnaFn6CWnf --- tests/integration/tests_playwright/test_call_script.py | 9 ++++----- 1 file changed, 4 insertions(+), 5 deletions(-) diff --git a/tests/integration/tests_playwright/test_call_script.py b/tests/integration/tests_playwright/test_call_script.py index 96dd3719129..5526150a6d8 100644 --- a/tests/integration/tests_playwright/test_call_script.py +++ b/tests/integration/tests_playwright/test_call_script.py @@ -15,6 +15,10 @@ def CallScript(): from pathlib import Path import reflex as rx + from reflex.utils.exceptions import ( + BrowserResultSerializationError, + BrowserScriptError, + ) inline_scripts = """ let inline_counter = 0 @@ -48,11 +52,6 @@ class CallScriptState(rx.State): @rx.event(background=True) async def await_results(self): - from reflex.utils.exceptions import ( - BrowserResultSerializationError, - BrowserScriptError, - ) - seen: list[str] = [ repr(await rx.call_script("inline3()")), repr(await rx.call_script("inline4()")), From 37feb97191e492b927c647605f025ef51c5108ab Mon Sep 17 00:00:00 2001 From: Farhan Date: Sat, 21 Nov 2026 21:27:46 +0000 Subject: [PATCH 07/13] Make BrowserScriptError picklable Pass name, message and stack to Exception.__init__ so the error survives pickling, and format it in __str__; an error the backend found itself has no JavaScript name and prints its message alone. Claude-Session: https://claude.ai/code/session_01LwJUCVxPh3ihrnaFn6CWnf --- .../src/reflex_base/utils/exceptions.py | 20 ++++++++-- .../reflex_base/utils/test_exceptions.py | 40 ++++++++++++++++++- 2 files changed, 56 insertions(+), 4 deletions(-) diff --git a/packages/reflex-base/src/reflex_base/utils/exceptions.py b/packages/reflex-base/src/reflex_base/utils/exceptions.py index 835123d369c..183c595f012 100644 --- a/packages/reflex-base/src/reflex_base/utils/exceptions.py +++ b/packages/reflex-base/src/reflex_base/utils/exceptions.py @@ -333,18 +333,32 @@ def __init__(self, name: str, message: str, stack: str = ""): """Create the error from the JavaScript error the browser reported. Args: - name: The JavaScript error's name, such as ``TypeError``. + name: The JavaScript error's name, such as ``TypeError``; empty + when the backend, not the browser, found the error. message: Its message. stack: Its stack trace, if the browser had one. """ - super().__init__(f"{name}: {message}") + # All three are the args, so the error survives pickling. + super().__init__(name, message, stack) self.name = name self.message = message self.stack = stack + def __str__(self) -> str: + """Format the error like the browser console does. + + Returns: + ``name: message``, or the message alone when there is no name. + """ + return f"{self.name}: {self.message}" if self.name else self.message + class BrowserResultSerializationError(BrowserScriptError): - """Raised when an awaited browser call returns a value JSON cannot carry.""" + """Raised when the result of an awaited browser call cannot reach the backend. + + The value is not one JSON can carry, or the backend cannot read the JSON + the browser sent. + """ class BrowserDisconnectedError(ReflexError, ConnectionError): diff --git a/tests/units/reflex_base/utils/test_exceptions.py b/tests/units/reflex_base/utils/test_exceptions.py index 5188e27013f..f359f3c4d1b 100644 --- a/tests/units/reflex_base/utils/test_exceptions.py +++ b/tests/units/reflex_base/utils/test_exceptions.py @@ -1,8 +1,14 @@ """Tests for reflex_base.utils.exceptions.""" +import pickle from unittest import mock -from reflex_base.utils.exceptions import ReflexError +import pytest +from reflex_base.utils.exceptions import ( + BrowserResultSerializationError, + BrowserScriptError, + ReflexError, +) def test_base_var_shadows_inherited_var_error_is_deprecated(): @@ -18,3 +24,35 @@ def test_base_var_shadows_inherited_var_error_is_deprecated(): deprecation_version="0.11.0", removal_version="1.0", ) + + +@pytest.mark.parametrize( + ("error_cls", "fields", "text"), + [ + ( + BrowserScriptError, + ("TypeError", "x is undefined", "at :1"), + "TypeError: x is undefined", + ), + ( + BrowserResultSerializationError, + ("", "The value is nested too deeply.", ""), + "The value is nested too deeply.", + ), + ], +) +def test_browser_script_error_formats_and_pickles( + error_cls: type[BrowserScriptError], fields: tuple[str, str, str], text: str +): + """A browser script error reads like the console, and survives pickling. + + Args: + error_cls: The error class. + fields: Its name, message and stack. + text: Its expected text. + """ + error = error_cls(*fields) + copy = pickle.loads(pickle.dumps(error)) + assert [ + (type(e), (e.name, e.message, e.stack), e.args, str(e)) for e in (error, copy) + ] == [(error_cls, fields, fields, text)] * 2 From 1b647a4aae27d3352c7731758787ed620d0e9816 Mon Sep 17 00:00:00 2001 From: Farhan Date: Sat, 21 Nov 2026 21:27:46 +0000 Subject: [PATCH 08/13] Allow browser_call_timeout=None to wait without a limit A call's own timeout=None already waits without a limit; the config setting can now say the same. Claude-Session: https://claude.ai/code/session_01LwJUCVxPh3ihrnaFn6CWnf --- packages/reflex-base/src/reflex_base/config.py | 4 ++-- tests/units/test_config.py | 18 ++++++++++++++++++ 2 files changed, 20 insertions(+), 2 deletions(-) diff --git a/packages/reflex-base/src/reflex_base/config.py b/packages/reflex-base/src/reflex_base/config.py index 839fee0229f..ce8a373f9dd 100644 --- a/packages/reflex-base/src/reflex_base/config.py +++ b/packages/reflex-base/src/reflex_base/config.py @@ -203,7 +203,7 @@ class BaseConfig: disable_plugins: List of plugin types to disable in the app. transport: The transport method for client-server communication. event_loop_blocking_threshold: Minimum event-loop blocking duration in seconds to report in development. Set to 0 to disable detection. - browser_call_timeout: Seconds an awaited browser call, such as `await rx.call_script(...)` in a background event handler, waits for the browser's result before raising TimeoutError. A call's own `timeout=` overrides it. + browser_call_timeout: Seconds an awaited browser call, such as `await rx.call_script(...)` in a background event handler, waits for the browser's result before raising TimeoutError, or None to wait without a limit. A call's own `timeout=` overrides it. browser_call_grace_period: Seconds an awaited browser call survives its tab disconnecting: a reconnect within it delivers the result, otherwise the call raises BrowserDisconnectedError. """ @@ -302,7 +302,7 @@ class BaseConfig: event_loop_blocking_threshold: float = 0.2 - browser_call_timeout: float = 30.0 + browser_call_timeout: float | None = 30.0 browser_call_grace_period: float = 5.0 diff --git a/tests/units/test_config.py b/tests/units/test_config.py index 8eabd94dd1b..198519e2b4b 100644 --- a/tests/units/test_config.py +++ b/tests/units/test_config.py @@ -107,6 +107,24 @@ def test_event_loop_blocking_detection_can_be_disabled_from_env( assert config.update_from_env()["event_loop_blocking_threshold"] == 0 +def test_browser_call_timeout_can_wait_without_a_limit( + base_config_values, monkeypatch: pytest.MonkeyPatch +): + """The awaited browser call timeout is None for no limit, or seconds from the environment.""" + assert rx.Config(**base_config_values).browser_call_timeout == pytest.approx(30) + assert ( + rx.Config(**base_config_values, browser_call_timeout=None).browser_call_timeout + is None + ) + monkeypatch.setenv("REFLEX_BROWSER_CALL_TIMEOUT", "12.5") + monkeypatch.setenv("REFLEX_BROWSER_CALL_GRACE_PERIOD", "0.5") + updated = rx.Config(**base_config_values).update_from_env() + assert ( + updated["browser_call_timeout"], + updated["browser_call_grace_period"], + ) == (12.5, 0.5) + + @pytest.mark.parametrize("trusted_proxy_hops", [-1, True, False, 1.5, "2", None]) def test_trusted_proxy_hops_must_be_non_negative( base_config_values, trusted_proxy_hops From 863c878c392fc794076febdb27e87b0d09478ef5 Mon Sep 17 00:00:00 2001 From: Farhan Date: Sat, 21 Nov 2026 21:27:47 +0000 Subject: [PATCH 09/13] Keep the timeout of a browser call off the wire The timeout only matters to the backend task that awaits the call, so it is kept on the spec (_BrowserCallSpec) instead of in the event args: a trigger or a yielded script no longer sends an unused timeout to the browser. Claude-Session: https://claude.ai/code/session_01LwJUCVxPh3ihrnaFn6CWnf --- .../src/reflex_base/event/__init__.py | 63 ++++++++++++------- .../event/processor/base_state_processor.py | 29 ++++----- tests/units/reflex_base/event/test_init.py | 38 +++++++---- 3 files changed, 77 insertions(+), 53 deletions(-) diff --git a/packages/reflex-base/src/reflex_base/event/__init__.py b/packages/reflex-base/src/reflex_base/event/__init__.py index 2e1f3b826f3..4f847f2345c 100644 --- a/packages/reflex-base/src/reflex_base/event/__init__.py +++ b/packages/reflex-base/src/reflex_base/event/__init__.py @@ -2083,6 +2083,20 @@ def download( ) +@dataclasses.dataclass(init=True, frozen=True, kw_only=True, eq=False) +class _BrowserCallSpec(EventSpec): + """The spec of a script run in the browser, whose result a background handler can await. + + Attributes: + timeout: Seconds an awaited call waits for the result, None for no + limit, or Unset for ``rx.Config.browser_call_timeout``. It is not + one of the args, which go to the browser, since only the backend + uses it. + """ + + timeout: float | Unset | None = Unset() + + @lru_cache def _script_signature(fn: Callable) -> inspect.Signature: """Get the signature of a script event, without the timeout of an awaited call. @@ -2101,28 +2115,36 @@ def _script_signature(fn: Callable) -> inspect.Signature: ) -def _script_kwargs( - callback: "EventType[Any] | None", timeout: float | Unset | None -) -> dict[str, Any]: - """Build the arguments a script event takes besides its code. +def _browser_call_spec( + name: str, + fn: Callable, + callback: "EventType[Any] | None", + timeout: float | Unset | None, + **kwargs: Any, +) -> EventSpec: + """Build the spec of a script event, which a background handler can await. Args: + name: The name of the event. + fn: The function creating the script event. callback: EventHandler that will receive the result of the script. - timeout: Seconds to wait for the result when it is awaited; left out when unset. + timeout: Seconds an awaited call waits for the result. + **kwargs: The script, under the name the frontend reads it from. Returns: - The callback, as the javascript that queues it, and the timeout if set. + The spec of the script event. """ - kwargs: dict[str, Any] = { - "callback": None + spec = server_side( + name, + _script_signature(fn), + **kwargs, + callback=None if callback is None else str( format.format_queue_events(callback, args_spec=lambda result: [result]) - ) - } - if not isinstance(timeout, Unset): - kwargs["timeout"] = timeout - return kwargs + ), + ) + return _BrowserCallSpec(handler=spec.handler, args=spec.args, timeout=timeout) def call_script( @@ -2155,11 +2177,8 @@ def call_script( # Without VarData, cast to string and eval the code in the event loop. javascript_code = str(Var(_js_expr=original_code)) - return server_side( - "_call_script", - _script_signature(call_script), - javascript_code=javascript_code, - **_script_kwargs(callback, timeout), + return _browser_call_spec( + "_call_script", call_script, callback, timeout, javascript_code=javascript_code ) @@ -2187,11 +2206,8 @@ def call_function( Var(javascript_code) if isinstance(javascript_code, str) else javascript_code ) - return server_side( - "_call_function", - _script_signature(call_function), - function=javascript_code, - **_script_kwargs(callback, timeout), + return _browser_call_spec( + "_call_function", call_function, callback, timeout, function=javascript_code ) @@ -3607,6 +3623,7 @@ class EventNamespace: EventHandler: TypeAlias = EventHandler EventSpec: TypeAlias = EventSpec CallableEventSpec: TypeAlias = CallableEventSpec + _BrowserCallSpec: TypeAlias = _BrowserCallSpec EventChain: TypeAlias = EventChain EventVar: TypeAlias = EventVar LiteralEventVar: TypeAlias = LiteralEventVar diff --git a/packages/reflex-base/src/reflex_base/event/processor/base_state_processor.py b/packages/reflex-base/src/reflex_base/event/processor/base_state_processor.py index 4dc393d087e..12b2a025f77 100644 --- a/packages/reflex-base/src/reflex_base/event/processor/base_state_processor.py +++ b/packages/reflex-base/src/reflex_base/event/processor/base_state_processor.py @@ -28,6 +28,7 @@ Event, EventHandler, EventSpec, + _BrowserCallSpec, _is_bound_event_handler, ) from reflex_base.event.context import EventContext @@ -38,7 +39,7 @@ from reflex_base.utils.form import form_data_as_dict, transform_form_data from reflex_base.utils.format import format_event_handler from reflex_base.utils.serializers import deserializers -from reflex_base.utils.types import is_non_string_sequence +from reflex_base.utils.types import Unset, is_non_string_sequence logger = logging.getLogger(__name__) @@ -579,16 +580,16 @@ def ensure_locked( return None -# The frontend events whose result the backend can await. -_BROWSER_CALL_EVENTS = frozenset({"_call_script", "_call_function"}) - - -async def _await_browser_call(ctx: EventContext, event: Event) -> Any: +async def _await_browser_call( + ctx: EventContext, event: Event, timeout: float | Unset | None +) -> Any: """Run a script in the client's browser and wait for its result. Args: ctx: The active EventContext of the client. event: The ``_call_script`` or ``_call_function`` event. + timeout: Seconds to wait for the result, None for no limit, or Unset + for ``rx.Config.browser_call_timeout``. Returns: The script's result. @@ -605,20 +606,14 @@ async def _await_browser_call(ctx: EventContext, event: Event) -> Any: "await it in a background event handler, outside `async with self`." ) raise EventHandlerTypeError(msg) - payload = event.payload - if payload.get("callback") is not None: + if event.payload["callback"] is not None: msg = ( f"`{event.name}` was given a callback and awaited; pass either " "callback= or await its result, not both." ) raise EventHandlerTypeError(msg) - # _to_event built this payload for this event alone, so it is the - # event's to change. - timeout = ( - payload.pop("timeout") - if "timeout" in payload - else get_config().browser_call_timeout - ) + if isinstance(timeout, Unset): + timeout = get_config().browser_call_timeout return await ctx.call_frontend(event, timeout) @@ -665,8 +660,8 @@ async def execute_event_inline(spec: EventSpec) -> Any: raise EventHandlerTypeError(msg) event = spec._to_event(ctx.router_data) name = event.name - if name in _BROWSER_CALL_EVENTS: - return await _await_browser_call(ctx, event) + if isinstance(spec, _BrowserCallSpec): + return await _await_browser_call(ctx, event, spec.timeout) if spec.client_handler_name: msg = f"Upload event `{name}` cannot be awaited; use it as an event trigger." raise EventHandlerTypeError(msg) diff --git a/tests/units/reflex_base/event/test_init.py b/tests/units/reflex_base/event/test_init.py index 1422f3949ba..e73cd5079f4 100644 --- a/tests/units/reflex_base/event/test_init.py +++ b/tests/units/reflex_base/event/test_init.py @@ -7,13 +7,16 @@ EventArgVar, EventChain, LambdaEventCallback, + _BrowserCallSpec, event_arg_placeholder, event_args_signature, no_args_event_spec, parse_args_spec, passthrough_event_spec, ) -from reflex_base.vars.base import Var +from reflex_base.utils.types import Unset +from reflex_base.vars import VarData +from reflex_base.vars.base import LiteralVar, Var from reflex_base.vars.number import NumberVar import reflex as rx @@ -100,19 +103,28 @@ def test_cond_between_function_and_none_inside_lambda_is_a_no_op_when_false() -> ) -def test_script_events_carry_a_timeout_only_when_given(): - """A timeout passed to a script event is in its payload; an unset one is not.""" - assert [ - spec._to_event().payload - for spec in ( - rx.call_script("1"), +def test_script_events_keep_their_timeout_off_the_wire(): + """A script event's timeout stays on the spec: neither its payload nor its compiled trigger has it.""" + hooked = Var(_js_expr="y", _var_data=VarData(hooks={"const y = 1;": None})) + specs = cast( + "list[_BrowserCallSpec]", + [ rx.call_script("1", timeout=5), + rx.call_script(f"f({hooked})", timeout=3), + rx.call_script(Var(_js_expr="code"), timeout=4), rx.call_function("() => 1", timeout=None), rx.run_script("2", timeout=1.5), - ) - ] == [ - {"javascript_code": "1", "callback": None}, - {"javascript_code": "1", "callback": None, "timeout": 5}, - {"function": "() => 1", "callback": None, "timeout": None}, - {"function": "(() => 2)", "callback": None, "timeout": 1.5}, + ], + ) + assert [(spec._to_event().payload, spec.timeout) for spec in specs] == [ + ({"javascript_code": "1", "callback": None}, 5), + ({"javascript_code": '("f("+y+")")', "callback": None}, 3), + ({"javascript_code": "code", "callback": None}, 4), + ({"function": "() => 1", "callback": None}, None), + ({"function": "(() => 2)", "callback": None}, 1.5), ] + assert str(LiteralVar.create(specs[0])) == ( + '(ReflexEvent("_call_script", ({ ["javascript_code"] : "1", ' + '["callback"] : null }), ({ })))' + ) + assert isinstance(cast("_BrowserCallSpec", rx.call_script("1")).timeout, Unset) From 717217dbbc573199b45686b90dffe447140c3a16 Mon Sep 17 00:00:00 2001 From: Farhan Date: Sat, 21 Nov 2026 21:27:54 +0000 Subject: [PATCH 10/13] Answer an awaited script even when its thrown value cannot be read A thrown value whose name or message getter throws, or a revoked Proxy, made describeScriptError throw, so the backend never got a reply and waited for its timeout. It now gets a generic error instead. The error for a function or symbol result also says what to return instead. Claude-Session: https://claude.ai/code/session_01LwJUCVxPh3ihrnaFn6CWnf --- packages/reflex-frontend/src/utils/state.js | 29 ++++++++++---- .../reflex-frontend/tests/run_script.test.js | 40 +++++++++++++++++-- 2 files changed, 58 insertions(+), 11 deletions(-) diff --git a/packages/reflex-frontend/src/utils/state.js b/packages/reflex-frontend/src/utils/state.js index 4eca746405c..e528a10e2d0 100644 --- a/packages/reflex-frontend/src/utils/state.js +++ b/packages/reflex-frontend/src/utils/state.js @@ -36,6 +36,10 @@ const RESULT_EVENT = "result"; // SERIALIZATION_ERROR_KIND in reflex_base/event/processor/browser_calls.py). const SERIALIZATION_ERROR_KIND = "serialization"; +// What the backend is told when even reading what a script threw throws. +const UNDESCRIBABLE_ERROR = + "The script threw a value whose name, message or stack cannot be read."; + // sessionStorage key with the time of the last automatic reload (must match // LAST_RELOADED_KEY in reflex/state.py: the reload on a frontend error and the // reload on a state mismatch share one cooldown, so neither can loop). @@ -639,16 +643,27 @@ const toText = (value) => { /** * Describe an error a script threw, for the backend that awaits its result. + * + * Reading the thrown value can throw as well (a getter that throws, a revoked + * Proxy). The backend still gets an error then, or it would wait for its + * timeout. * @param error The thrown value, which need not be an Error. * @param kind The kind of failure, if it is not the script's own. * @returns The error's name, message and stack. */ -const describeScriptError = (error, kind = undefined) => ({ - name: toText(error?.name ?? "Error"), - message: toText(error instanceof Error ? error.message : error), - stack: toText(error?.stack ?? ""), - ...(kind === undefined ? {} : { kind }), -}); +const describeScriptError = (error, kind = undefined) => { + let described; + try { + described = { + name: toText(error?.name ?? "Error"), + message: toText(error instanceof Error ? error.message : error), + stack: toText(error?.stack ?? ""), + }; + } catch { + described = { name: "Error", message: UNDESCRIBABLE_ERROR, stack: "" }; + } + return kind === undefined ? described : { ...described, kind }; +}; /** * Serialize a script's result as JSON for the backend that awaits it. @@ -672,7 +687,7 @@ const serializeScriptResult = (value) => { }); if (json === undefined) { throw new TypeError( - `The script returned a ${typeof value}, which JSON cannot carry.`, + `The script returned a ${typeof value}, which JSON cannot carry; return plain data (objects, arrays, strings, numbers, booleans or null) instead.`, ); } return json; diff --git a/packages/reflex-frontend/tests/run_script.test.js b/packages/reflex-frontend/tests/run_script.test.js index 536b08f22a0..2cae6939269 100644 --- a/packages/reflex-frontend/tests/run_script.test.js +++ b/packages/reflex-frontend/tests/run_script.test.js @@ -221,8 +221,7 @@ describe("awaited script results", () => { }); test("describes a thrown value that cannot become a string", async () => { - // String() throws on an object without a prototype; the backend must - // still receive an error rather than wait for its timeout. + // String() throws on an object without a prototype. const { outcome } = awaited(script("Promise.reject(Object.create(null))")); expect(await outcome()).toEqual({ rid: "r1", @@ -230,6 +229,31 @@ describe("awaited script results", () => { }); }); + test.each([ + ["a value whose name getter throws", "({ get name() { throw 1; } })"], + [ + "a revoked Proxy", + "(() => { const p = Proxy.revocable({}, {}); p.revoke(); return p.proxy; })()", + ], + [ + "an Error whose message getter throws", + "Object.defineProperty(new Error(), 'message', { get() { throw 1; } })", + ], + ])("still answers the backend when it throws %s", async (_what, thrown) => { + // Reading the thrown value throws; the backend must still get an error + // rather than wait for its timeout. + const { outcome } = awaited(script(`Promise.reject(${thrown})`)); + expect(await outcome()).toEqual({ + rid: "r1", + error: { + name: "Error", + message: + "The script threw a value whose name, message or stack cannot be read.", + stack: "", + }, + }); + }); + test.each([ [ "a DOM node", @@ -253,7 +277,13 @@ describe("awaited script results", () => { "a function", "() => 1", "TypeError", - "The script returned a function, which JSON cannot carry.", + "The script returned a function, which JSON cannot carry; return plain data (objects, arrays, strings, numbers, booleans or null) instead.", + ], + [ + "a symbol", + "Symbol('s')", + "TypeError", + "The script returned a symbol, which JSON cannot carry; return plain data (objects, arrays, strings, numbers, booleans or null) instead.", ], ["a BigInt", "1n", "TypeError", "Do not know how to serialize a BigInt"], ])("rejects %s as a serialization error", async (_what, code, name, message) => { @@ -269,7 +299,9 @@ describe("awaited script results", () => { window.onerror = onerror; const socket = { emit: vi.fn() }; await applyEvent(script("throw new Error('boom')"), socket, null, null); - expect(onerror).toHaveBeenCalledTimes(1); + expect(onerror.mock.calls).toEqual([ + ["boom", null, null, null, new Error("boom")], + ]); expect(socket.emit).not.toHaveBeenCalled(); }); }); From e5d6617ec6e49ddb1aac61c7550131ae3484bfdd Mon Sep 17 00:00:00 2001 From: Farhan Date: Sat, 21 Nov 2026 21:28:03 +0000 Subject: [PATCH 11/13] Fail an awaited browser call at once when its page is gone A reloaded page reconnected under its sessionStorage token within the grace period, which kept calls whose script had died with the old page: they waited for their timeout, forever with timeout=None. The frontend now sends a random page id with every connect; a connect from another page load under the token fails the token's pending calls at once, while a reconnect of the same page keeps them. A call made between a socket's disconnect and the cleanup of its token passed the connected check and registered without a grace timer. The namespace now drops the page of a socket in on_disconnect itself, and a token whose socket has no page is not connected. Results settle their call by request id alone, so a tab that was given a new token on reconnect still delivers them. A result Python cannot parse (nested too deeply, or malformed) always fails its call instead of leaving it pending. The error messages say what happened, why, and what to change. Claude-Session: https://claude.ai/code/session_01LwJUCVxPh3ihrnaFn6CWnf --- .../src/reflex_base/constants/compiler.py | 3 + .../src/reflex_base/event/context.py | 12 +- .../event/processor/browser_calls.py | 176 ++++++++----- .../event/processor/event_processor.py | 19 +- packages/reflex-frontend/README.md | 5 +- packages/reflex-frontend/src/utils/state.js | 16 +- .../tests/state_connection.test.js | 58 +++- reflex/app.py | 45 ++-- .../processor/test_base_state_processor.py | 8 +- .../event/processor/test_browser_calls.py | 248 +++++++++++++----- .../event/processor/test_event_processor.py | 47 ++-- tests/units/test_app.py | 131 ++++++--- 12 files changed, 557 insertions(+), 211 deletions(-) diff --git a/packages/reflex-base/src/reflex_base/constants/compiler.py b/packages/reflex-base/src/reflex_base/constants/compiler.py index 48a21df1ed2..05ca82b1aa0 100644 --- a/packages/reflex-base/src/reflex_base/constants/compiler.py +++ b/packages/reflex-base/src/reflex_base/constants/compiler.py @@ -64,6 +64,9 @@ class CompileVars(SimpleNamespace): # The key of the CONNECT auth packet that carries the hash of the state # tree the frontend was compiled for; an old frontend sends none. CONNECT_AUTH_STATE_SCHEMA = "state_schema" + # The key of the CONNECT auth packet that carries the id of the page load, + # which tells a reconnect of the page from a reload. + CONNECT_AUTH_PAGE = "page" # Payload keys of hydrate_and_load / update_vars_internal; they are passed # through as handler kwargs, so they must match those parameter names. PAYLOAD_VARS = "vars" diff --git a/packages/reflex-base/src/reflex_base/event/context.py b/packages/reflex-base/src/reflex_base/event/context.py index 07677f03c2a..d91378ddaa7 100644 --- a/packages/reflex-base/src/reflex_base/event/context.py +++ b/packages/reflex-base/src/reflex_base/event/context.py @@ -135,8 +135,7 @@ class EventContext(BaseContext): emit_event_impl: EmitEventProtocol | None = dataclasses.field( default=None, repr=False ) - # Runs a frontend event in the browser and returns its result; None when - # no frontend is attached. + # None when no frontend is attached. call_frontend_impl: CallFrontendProtocol | None = dataclasses.field( default=None, repr=False ) @@ -277,7 +276,14 @@ async def call_frontend(self, event: Event, timeout: float | None) -> Any: BrowserDisconnectedError: If no frontend is attached to the app. """ if self.call_frontend_impl is None: - msg = "No browser is connected to this app, so it cannot run the script." + msg = ( + f"`{event.name}` cannot run in a browser: the app is running " + "without a frontend connection (for example in a test, or a " + "process that runs only the backend), so no tab can return a " + "result. Await browser scripts in handlers triggered from a page " + "of the running app, and catch BrowserDisconnectedError where no " + "page may be connected." + ) raise BrowserDisconnectedError(msg) return await self.call_frontend_impl(self.token, event, timeout) diff --git a/packages/reflex-base/src/reflex_base/event/processor/browser_calls.py b/packages/reflex-base/src/reflex_base/event/processor/browser_calls.py index e4f354d1d59..f8c64ad0a30 100644 --- a/packages/reflex-base/src/reflex_base/event/processor/browser_calls.py +++ b/packages/reflex-base/src/reflex_base/event/processor/browser_calls.py @@ -24,28 +24,41 @@ # The payload key of a browser call's request id (must match state.js). RID_KEY = "rid" +_PAGE_REPLACED = ( + "The browser tab reloaded or left the page before the script returned a " + "result, so the script stopped. Catch BrowserDisconnectedError where the " + "user may reload or leave the page while the script runs." +) + + +@dataclasses.dataclass(slots=True) +class _Tab: + """The calls awaiting the results of one client token's tab.""" + + # The page load the calls were sent to: a script stops with its page. + page: str + rids: set[str] = dataclasses.field(default_factory=set) + # Set while the tab is disconnected; fails the calls unless it reconnects. + grace_timer: asyncio.TimerHandle | None = None + @dataclasses.dataclass(slots=True) class BrowserCalls: - """The browser calls waiting for a result, per client token. + """The browser calls waiting for a result. - A result resolves a call only when it comes from the token the call was - sent to, so one tab cannot answer another tab's call. + A result settles the call with its request id, whichever socket it comes + from: the id is random and only ever sent to the tab the call runs in, + which may have been given a new token when it reconnected. """ - # Client token -> request id -> the future its result resolves. - _pending: dict[str, dict[str, asyncio.Future[Any]]] = dataclasses.field( - default_factory=dict - ) - # Client token -> the timer that fails its calls once the grace period - # after a disconnect is over. - _grace_timers: dict[str, asyncio.TimerHandle] = dataclasses.field( - default_factory=dict - ) + _futures: dict[str, asyncio.Future[Any]] = dataclasses.field(default_factory=dict) + # Client token -> the calls sent to its tab, failed when it goes away. + _tabs: dict[str, _Tab] = dataclasses.field(default_factory=dict) async def call( self, token: str, + page: str, event: Event, timeout: float | None, emit: Callable[[str, Event], Awaitable[Any]], @@ -54,6 +67,7 @@ async def call( Args: token: The client token to send the event to. + page: The page load the token's tab connected from. event: The frontend event to run in the browser. timeout: Seconds to wait for the result, or None to wait until it arrives. emit: Sends an event to a client. @@ -65,9 +79,11 @@ async def call( TimeoutError: If no result arrives within the timeout. """ rid = uuid.uuid4().hex - future = asyncio.get_running_loop().create_future() - calls = self._pending.setdefault(token, {}) - calls[rid] = future + future = self._futures[rid] = asyncio.get_running_loop().create_future() + tab = self._tabs.get(token) + if tab is None: + tab = self._tabs[token] = _Tab(page) + tab.rids.add(rid) try: # Only the browser-call events carry a request id, in their # payload, so no other event pays for it. @@ -80,32 +96,36 @@ async def call( except TimeoutError: msg = ( f"The browser did not return a result for `{event.name}` " - f"within {timeout} seconds." + f"within {timeout} seconds. If the script needs longer, pass " + "a longer `timeout=` to the call (or `timeout=None` to wait " + "without a limit) or raise `browser_call_timeout` in " + "rxconfig.py; if it returns a promise, make sure the " + "promise settles." ) raise TimeoutError(msg) from None finally: - calls.pop(rid, None) - # The token's calls may have been failed on a disconnect already, - # which drops this mapping from _pending. - if not calls and self._pending.get(token) is calls: - del self._pending[token] - if (timer := self._grace_timers.pop(token, None)) is not None: - timer.cancel() - - def resolve(self, token: str, rid: str, outcome: Mapping[str, Any]) -> None: + del self._futures[rid] + tab.rids.remove(rid) + # A disconnect may have failed the tab's calls already, and a new + # call made a new _Tab for the token. + if not tab.rids and self._tabs.get(token) is tab: + del self._tabs[token] + if tab.grace_timer is not None: + tab.grace_timer.cancel() + + def resolve(self, rid: str, outcome: Mapping[str, Any]) -> None: """Settle a call with the outcome the browser reported for it. - An outcome for a call that is no longer waiting (it timed out, or the - token never made it) is dropped. + An outcome for a call that is no longer waiting (it timed out, or was + never made) is dropped. Args: - token: The client token the outcome came from. rid: The request id of the call. outcome: ``{"json": }``, or ``{"error": {"name", "message", "stack", "kind"}}`` when the script failed. """ - calls = self._pending.get(token) - if calls is None or (future := calls.pop(rid, None)) is None or future.done(): + future = self._futures.get(rid) + if future is None or future.done(): return error = outcome.get("error") if isinstance(error, Mapping): @@ -123,65 +143,97 @@ def resolve(self, token: str, rid: str, outcome: Mapping[str, Any]) -> None: ) return try: - future.set_result(json.loads(outcome["json"])) - except (KeyError, TypeError, ValueError) as e: + # A missing or non-string field raises the TypeError reported below. + future.set_result(json.loads(outcome.get("json"))) # pyright: ignore[reportArgumentType] + except (TypeError, ValueError) as e: + future.set_exception( + BrowserResultSerializationError( + "", + f"The browser sent a result the backend cannot read ({e}). " + "The page runs a frontend built for another version of " + "Reflex: rebuild the frontend (restart `reflex run`, or " + "export the app again) and reload the page.", + ) + ) + except RecursionError: future.set_exception( BrowserResultSerializationError( - type(e).__name__, f"The browser sent a malformed result: {e}" + "", + "The script returned a value nested too deeply for Python's " + "JSON parser. Return a value with fewer levels of nested " + "objects and arrays.", ) ) def disconnect(self, token: str, grace_period: float) -> None: """Start the grace period of a client's calls after it disconnected. - The tab may reconnect within it, and its results then still arrive. + Its tab may reconnect within it, and its results then still arrive. Args: token: The disconnected client token. grace_period: Seconds to wait for the client to reconnect. """ - if token not in self._pending or token in self._grace_timers: - return - if grace_period <= 0: - self._fail(token) + if (tab := self._tabs.get(token)) is None: return - self._grace_timers[token] = asyncio.get_running_loop().call_later( - grace_period, self._fail, token + msg = ( + "The browser tab disconnected and did not reconnect within " + f"browser_call_grace_period ({grace_period} seconds), so the script's " + "result is lost: the tab was closed, or lost its connection. Catch " + "BrowserDisconnectedError where the user may close the tab, or raise " + "`browser_call_grace_period` in rxconfig.py if connections drop for " + "longer." ) + if grace_period <= 0: + self._fail(token, msg) + else: + tab.grace_timer = asyncio.get_running_loop().call_later( + grace_period, self._fail, token, msg + ) - def reconnect(self, token: str) -> None: + def connect(self, token: str, page: str) -> None: """End the grace period of a client that connected again. + A connect from another page load means the page the calls run in + reloaded or navigated away, so they fail at once. + Args: - token: The reconnected client token. + token: The connected client token. + page: The page load it connected from. """ - if (timer := self._grace_timers.pop(token, None)) is not None: - timer.cancel() + tab = self._tabs.get(token) + # A tab that is still connected keeps its calls: another tab + # connecting with its token is a duplicate, given a new token. + if tab is None or tab.grace_timer is None: + return + if tab.page == page: + tab.grace_timer.cancel() + tab.grace_timer = None + else: + self._fail(token, _PAGE_REPLACED) def close(self) -> None: """Cancel every pending call, as the backend shuts down.""" - for timer in self._grace_timers.values(): - timer.cancel() - self._grace_timers.clear() - for calls in self._pending.values(): - for future in calls.values(): - future.cancel() - self._pending.clear() + for tab in self._tabs.values(): + if tab.grace_timer is not None: + tab.grace_timer.cancel() + for future in self._futures.values(): + future.cancel() - def _fail(self, token: str) -> None: - """Fail a client's calls: it did not reconnect within the grace period. + def _fail(self, token: str, message: str) -> None: + """Fail a client's calls with BrowserDisconnectedError. Args: - token: The disconnected client token. + token: The client token. + message: The error's message. """ - self._grace_timers.pop(token, None) - for future in self._pending.pop(token, {}).values(): - if not future.done(): - future.set_exception( - BrowserDisconnectedError( - "The browser tab disconnected before returning a result." - ) - ) + tab = self._tabs.pop(token) + if tab.grace_timer is not None: + tab.grace_timer.cancel() + for rid in tab.rids: + # A result may have settled the call, which has not resumed yet. + if not (future := self._futures[rid]).done(): + future.set_exception(BrowserDisconnectedError(message)) __all__ = ["BrowserCalls"] diff --git a/packages/reflex-base/src/reflex_base/event/processor/event_processor.py b/packages/reflex-base/src/reflex_base/event/processor/event_processor.py index 477663f802d..1acc0c38003 100644 --- a/packages/reflex-base/src/reflex_base/event/processor/event_processor.py +++ b/packages/reflex-base/src/reflex_base/event/processor/event_processor.py @@ -235,13 +235,19 @@ async def call_frontend( Raises: BrowserDisconnectedError: If the client is not connected to this backend. """ - if not event_namespace._is_connected(token): + if (page := event_namespace._page_of(token)) is None: msg = ( - f"The browser tab is not connected, so `{event.name}` " - "cannot run in it." + f"`{event.name}` cannot run in the browser tab: the tab " + "is not connected to this backend worker, because it " + "was closed, is reconnecting, or reconnected to another " + "worker. Catch BrowserDisconnectedError where the tab may " + "be gone; with several backend workers, route each tab " + "to one worker (sticky sessions)." ) raise BrowserDisconnectedError(msg) - return await self._browser_calls.call(token, event, timeout, emit_event) + return await self._browser_calls.call( + token, page, event, timeout, emit_event + ) call_frontend_impl = call_frontend @@ -532,13 +538,14 @@ def _on_disconnect(self, token: str) -> None: """ self._browser_calls.disconnect(token, self.browser_call_grace_period) - def _on_connect(self, token: str) -> None: + def _on_connect(self, token: str, page: str) -> None: """Handle a client connecting, possibly again after a disconnect. Args: token: The connected client token. + page: The page load the client connected from. """ - self._browser_calls.reconnect(token) + self._browser_calls.connect(token, page) async def enqueue_many(self, token: str, *events: Event) -> Sequence[EventFuture]: """Enqueue multiple events to be processed. diff --git a/packages/reflex-frontend/README.md b/packages/reflex-frontend/README.md index 712a67f3c6d..aaee7d12575 100644 --- a/packages/reflex-frontend/README.md +++ b/packages/reflex-frontend/README.md @@ -46,8 +46,9 @@ Several of the bugs found in this code came from state a function reads or write without it appearing in its arguments. What there is, and where it is pinned: - **Module-level state in `utils/state.js`**: the event queue, the session - token, the socket warmed up before React mounts, the record of sent - localStorage values. Every mounted event loop and every drain shares them. + token, the id of the page load (sent on every connect, so the backend tells + a reconnect from a reload), the socket warmed up before React mounts, the + record of sent localStorage values. Every mounted event loop and every drain shares them. A test that needs a clean copy reloads the module (`vi.resetModules()`, as `tests/state_connection.test.js` does). Code that awaits must not assume the queue or the socket is as it left them. diff --git a/packages/reflex-frontend/src/utils/state.js b/packages/reflex-frontend/src/utils/state.js index e528a10e2d0..5bc0cfafa14 100644 --- a/packages/reflex-frontend/src/utils/state.js +++ b/packages/reflex-frontend/src/utils/state.js @@ -170,6 +170,10 @@ export const getToken = () => { return token; }; +// Sent on every connect, so the backend tells a reconnect of this page from a +// reload: the scripts it awaits stop with the page that runs them. +const PAGE_ID = generateUUID(); + /** * Get the token for the current session without saving a new one. * @@ -1226,16 +1230,20 @@ export const connect = async ( // The hydrate event rides in the socket.io CONNECT packet, so the backend // starts loading state as soon as the namespace connects instead of after // an extra round trip for the connect acknowledgement. The keys are read by - // the backend as CompileVars.CONNECT_AUTH_EVENT and CONNECT_AUTH_STATE_SCHEMA; - // the state schema goes along on every (re)connect, since a reconnect can - // land on another backend version. + // the backend as CompileVars.CONNECT_AUTH_EVENT, CONNECT_AUTH_STATE_SCHEMA + // and CONNECT_AUTH_PAGE; the state schema goes along on every (re)connect, + // since a reconnect can land on another backend version. const bootAuth = (first) => (callback) => { const boot_event = withRouterData(app.initialEvents(first)[0], params); bootRoute = currentRouteKey(); recordSentStorageValues(boot_event); // Instrumentation hook (installed by reflex-otel): may add a traceparent. window.__reflex_otel?.onEventSend?.(boot_event); - callback({ event: boot_event, state_schema: app.stateSchema }); + callback({ + event: boot_event, + state_schema: app.stateSchema, + page: PAGE_ID, + }); }; // Create the socket. A new session's token is saved here, once the app has diff --git a/packages/reflex-frontend/tests/state_connection.test.js b/packages/reflex-frontend/tests/state_connection.test.js index b8d40202803..017376cc628 100644 --- a/packages/reflex-frontend/tests/state_connection.test.js +++ b/packages/reflex-frontend/tests/state_connection.test.js @@ -84,6 +84,17 @@ const sent = (socket) => const navigate = () => {}; const params = { current: {} }; +const appConfig = { + initialState: { reflex___state____state: {}, other: {} }, + initialEvents: () => [], + onLoadInternalEvent: () => [], + on_load_internal_event: "on_load_internal", + state_name: "reflex___state____state", + exception_state_name: "reflex___state____frontend_event_exception_state", + stateSchema: "schema", + clientStorage: {}, +}; + let state; let registry; // Sockets connected without an event loop around them, which nothing unmounts. @@ -99,16 +110,7 @@ beforeEach(async () => { // Let the import's speculative transport warmup see an app without state, // then give it one: an app with a single substate never connects. await Promise.resolve(); - registry.registerApp({ - initialState: { reflex___state____state: {}, other: {} }, - initialEvents: () => [], - onLoadInternalEvent: () => [], - on_load_internal_event: "on_load_internal", - state_name: "reflex___state____state", - exception_state_name: "reflex___state____frontend_event_exception_state", - stateSchema: "schema", - clientStorage: {}, - }); + registry.registerApp(appConfig); }); afterEach(() => { @@ -310,3 +312,39 @@ test("a connection that cannot be attempted is a connection error, not a rejecti expect(loop.connectErrors().at(-1)).toBe(denied); await loop.unmount(); }); + +test("every connect of a page load sends its page id, and a reload sends a new one", async () => { + const hydrate = { name: "reflex___state____state.hydrate_and_load" }; + // The CONNECT auth packet socket.io sends for a newly connected socket. + const connectAuth = async () => { + registry.registerApp({ + ...appConfig, + initialEvents: () => [{ ...hydrate }], + }); + const socketRef = await connectSocket(); + return new Promise((resolve) => socketRef.current.auth(resolve)); + }; + const first = await connectAuth(); + const again = await connectAuth(); + vi.resetModules(); + state = await import("$/utils/state"); + registry = await import("$/utils/context-registry"); + const reloaded = await connectAuth(); + + expect(typeof first.page).toBe("string"); + expect(again.page).toBe(first.page); + expect(reloaded.page).not.toBe(first.page); + // The page id is random; the rest of the packet is not. + expect( + [first, again, reloaded].map((auth) => ({ ...auth, page: "" })), + ).toEqual( + Array(3).fill({ + event: { + ...hydrate, + router_data: { pathname: "/", asPath: "/" }, + }, + state_schema: "schema", + page: "", + }), + ); +}); diff --git a/reflex/app.py b/reflex/app.py index a53e42c5f61..8d6d484283e 100644 --- a/reflex/app.py +++ b/reflex/app.py @@ -2684,6 +2684,10 @@ def __init__(self, namespace: str, app: App): # connect time instead of for every event on the connection. self._static_router_data: dict[str, dict[str, Any]] = {} + # The page load each SID connected from, dropped as soon as the socket + # disconnects: a script a backend task awaits stops with its page. + self._sid_pages: dict[str, str] = {} + # Start time and count of the current process-wide client_error window. self._client_error_window_start = 0.0 self._client_error_window_count = 0 @@ -2730,9 +2734,11 @@ async def on_connect(self, sid: str, environ: dict, auth: Any = None): # Make sure this instance is watching for updates from other instances. await self._token_manager.ensure_lost_and_found_subscribed(self.emit_update) boot_event = frontend_schema = None + page = "" if isinstance(auth, dict): boot_event = auth.get(constants.CompileVars.CONNECT_AUTH_EVENT) frontend_schema = auth.get(constants.CompileVars.CONNECT_AUTH_STATE_SCHEMA) + page = auth.get(constants.CompileVars.CONNECT_AUTH_PAGE, "") # A frontend compiled for another state tree is told so before it # hydrates; an older frontend sends no hash and is left alone. The # backend hash is cached on the state class, so this is one lookup. @@ -2763,9 +2769,15 @@ async def on_connect(self, sid: str, environ: dict, auth: Any = None): if token_list: # The boot event is the connection's first event: processing it # records the new sid and token on the state under the state lock. - await self.link_token_to_sid( + new_token = await self.link_token_to_sid( sid, token_list[0], update_state=boot_event is None ) + if ( + new_token is None + and (processor := self.app._event_processor) is not None + ): + # The tab's browser calls survive a reconnect of their page. + processor._on_connect(token_list[0], page) else: logger.warning(f"No token provided in connection for session {sid}") @@ -2780,6 +2792,7 @@ async def on_connect(self, sid: str, environ: dict, auth: Any = None): # Headers, client IP, and session id cannot change for the lifetime of # the connection; compute them once instead of on every event. self._static_router_data[sid] = self._build_static_router_data(sid, environ) + self._sid_pages[sid] = page if boot_event is not None: try: @@ -2789,6 +2802,7 @@ async def on_connect(self, sid: str, environ: dict, auth: Any = None): # token link and connection data made above before the error # refuses the connect. self._static_router_data.pop(sid, None) + self._sid_pages.pop(sid, None) if (linked_token := self.sid_to_token.get(sid)) is not None: await self._token_manager.disconnect_token(linked_token, sid) raise @@ -2847,6 +2861,7 @@ def on_disconnect(self, sid: str) -> asyncio.Task | None: otel.record_connection(-1) self._client_error_counts.pop(sid, None) self._static_router_data.pop(sid, None) + self._sid_pages.pop(sid, None) # Get token before cleaning up disconnect_token = self.sid_to_token.get(sid) if disconnect_token: @@ -2873,20 +2888,19 @@ def on_disconnect(self, sid: str) -> asyncio.Task | None: return task return None - def _is_connected(self, token: str) -> bool: - """Whether a client is connected to this instance of the backend. + def _page_of(self, token: str) -> str | None: + """Get the page load of a client's tab, while it is connected to this worker. Args: token: The client token. Returns: - True when the token's socket is connected to this instance. + The page id the tab connected with, or None when the token has no + socket on this worker. A socket loses its page as it disconnects, + before the token's link to it is cleaned up. """ socket_record = self._token_manager.token_to_socket.get(token) - return ( - socket_record is not None - and socket_record.instance_id == self._token_manager.instance_id - ) + return None if socket_record is None else self._sid_pages.get(socket_record.sid) async def emit_update( self, update: StateUpdate, token: str, suppress_warnings: bool = False @@ -3138,15 +3152,11 @@ async def on_result(self, sid: str, data: Any = None): if not isinstance(data, dict) or not isinstance(rid := data.get(RID_KEY), str): logger.debug(f"Ignoring malformed result payload from SID {sid}.") return - if (token := self.sid_to_token.get(sid)) is None or ( - processor := self.app._event_processor - ) is None: - return - processor._browser_calls.resolve(token, rid, data) + self.app.event_processor._browser_calls.resolve(rid, data) async def link_token_to_sid( self, sid: str, token: str, *, update_state: bool = True - ): + ) -> str | None: """Link a token to a session id. Args: @@ -3156,6 +3166,9 @@ async def link_token_to_sid( now. The connect skips it when the CONNECT packet carries the boot event, which records them as the connection's first event without an extra load and save of the whole state tree. + + Returns: + The new token the tab was given when its token is a duplicate, or None. """ # Use TokenManager for duplicate detection and Redis support new_token = await self._token_manager.link_token_to_sid(token, sid) @@ -3163,9 +3176,6 @@ async def link_token_to_sid( if new_token: # Duplicate detected, emit new token to client await self.emit("new_token", new_token, to=sid) - elif (processor := self.app._event_processor) is not None: - # A tab reconnecting within the grace period keeps its browser calls. - processor._on_connect(token) # Update client state to apply new sid/token for running background tasks. if update_state and self.app._state is not None: @@ -3181,3 +3191,4 @@ async def link_token_to_sid( session := SessionData.from_router_data(state.router_data) ) != state.rx_router_session: state.rx_router_session = session + return new_token diff --git a/tests/units/reflex_base/event/processor/test_base_state_processor.py b/tests/units/reflex_base/event/processor/test_base_state_processor.py index a48409bf903..de1d5e4a392 100644 --- a/tests/units/reflex_base/event/processor/test_base_state_processor.py +++ b/tests/units/reflex_base/event/processor/test_base_state_processor.py @@ -5914,5 +5914,11 @@ async def run(self): await future.wait_all() assert errors == [ - "No browser is connected to this app, so it cannot run the script." + ( + "`_call_script` cannot run in a browser: the app is running without a " + "frontend connection (for example in a test, or a process that runs " + "only the backend), so no tab can return a result. Await browser " + "scripts in handlers triggered from a page of the running app, and " + "catch BrowserDisconnectedError where no page may be connected." + ) ] diff --git a/tests/units/reflex_base/event/processor/test_browser_calls.py b/tests/units/reflex_base/event/processor/test_browser_calls.py index 49348ba4290..c1b05479da5 100644 --- a/tests/units/reflex_base/event/processor/test_browser_calls.py +++ b/tests/units/reflex_base/event/processor/test_browser_calls.py @@ -14,6 +14,31 @@ EVENT = Event(name="_call_script", payload={"javascript_code": "1", "callback": None}) +PAGE_REPLACED = ( + "The browser tab reloaded or left the page before the script returned a " + "result, so the script stopped. Catch BrowserDisconnectedError where the " + "user may reload or leave the page while the script runs." +) + + +def grace_expired(grace_period: float) -> str: + """The message of a call whose tab did not reconnect in time. + + Args: + grace_period: The grace period, in seconds. + + Returns: + The error message. + """ + return ( + "The browser tab disconnected and did not reconnect within " + f"browser_call_grace_period ({grace_period} seconds), so the script's " + "result is lost: the tab was closed, or lost its connection. Catch " + "BrowserDisconnectedError where the user may close the tab, or raise " + "`browser_call_grace_period` in rxconfig.py if connections drop for " + "longer." + ) + class Browser: """Records the events sent to it, like a connected tab.""" @@ -46,7 +71,7 @@ async def rid(self) -> str: async def _start_call( calls: BrowserCalls, timeout: float | None = None, token: str = "tok" ) -> tuple[Browser, asyncio.Task[Any], str]: - """Start a call and wait for its event to be sent. + """Start a call to the tab of page ``p1`` and wait for its event to be sent. Args: calls: The registry. @@ -57,10 +82,33 @@ async def _start_call( The browser, the task awaiting the call, and the call's request id. """ browser = Browser() - task = asyncio.create_task(calls.call(token, EVENT, timeout, browser.emit)) + task = asyncio.create_task(calls.call(token, "p1", EVENT, timeout, browser.emit)) return browser, task, await browser.rid() +async def _raised(task: asyncio.Task[Any]) -> tuple[type[BaseException], str]: + """Await a call that fails. + + Args: + task: The task awaiting the call. + + Returns: + The type and message of the exception it raised. + """ + with pytest.raises(Exception) as exc_info: + await task + return type(exc_info.value), str(exc_info.value) + + +def _assert_forgotten(calls: BrowserCalls) -> None: + """Assert the registry holds nothing of the calls made. + + Args: + calls: The registry. + """ + assert (calls._futures, calls._tabs) == ({}, {}) + + async def test_call_sends_the_event_with_a_request_id_and_returns_the_result(): """The browser receives the event with a rid in its payload; its JSON result is the call's value.""" calls = BrowserCalls() @@ -74,23 +122,22 @@ async def test_call_sends_the_event_with_a_request_id_and_returns_the_result(): ), ) ] - calls.resolve("tok", rid, {"rid": rid, "json": '{"a": [1, null]}'}) + calls.resolve(rid, {"rid": rid, "json": '{"a": [1, null]}'}) assert await task == {"a": [1, None]} - assert calls._pending == {} + _assert_forgotten(calls) -async def test_a_result_from_another_token_or_request_is_ignored(): - """Only the tab a call was sent to can answer it, and only under its rid.""" +async def test_a_result_settles_its_call_by_request_id_once(): + """A result for an unknown rid is dropped, and the first result for a call wins.""" calls = BrowserCalls() _, task, rid = await _start_call(calls) - calls.resolve("other", rid, {"json": "1"}) - calls.resolve("tok", "unknown", {"json": "2"}) + calls.resolve("unknown", {"json": "2"}) await asyncio.sleep(0) assert not task.done() - calls.resolve("tok", rid, {"json": "3"}) + calls.resolve(rid, {"json": "3"}) + calls.resolve(rid, {"json": "4"}) assert await task == 3 - # A late duplicate after the call settled is dropped. - calls.resolve("tok", rid, {"json": "4"}) + _assert_forgotten(calls) @pytest.mark.parametrize( @@ -137,7 +184,7 @@ async def test_an_error_the_browser_reports_is_raised( """ calls = BrowserCalls() _, task, rid = await _start_call(calls) - calls.resolve("tok", rid, {"rid": rid, "error": error}) + calls.resolve(rid, {"rid": rid, "error": error}) with pytest.raises(expected_type) as exc_info: await task exc = exc_info.value @@ -145,66 +192,101 @@ async def test_an_error_the_browser_reports_is_raised( assert (exc.name, exc.message, exc.stack, str(exc)) == expected +def _unreadable(detail: str) -> str: + """The message of a result the backend cannot read. + + Args: + detail: Why it cannot be read. + + Returns: + The error message. + """ + return ( + f"The browser sent a result the backend cannot read ({detail}). The page " + "runs a frontend built for another version of Reflex: rebuild the " + "frontend (restart `reflex run`, or export the app again) and reload the " + "page." + ) + + @pytest.mark.parametrize( ("outcome", "expected"), [ - ({}, "KeyError: The browser sent a malformed result: 'json'"), + ( + {}, + _unreadable( + "the JSON object must be str, bytes or bytearray, not NoneType" + ), + ), ( {"json": "{"}, - ( - "JSONDecodeError: The browser sent a malformed result: Expecting " - "property name enclosed in double quotes: line 1 column 2 (char 1)" + _unreadable( + "Expecting property name enclosed in double quotes: line 1 column 2 " + "(char 1)" ), ), ( {"json": 5}, + _unreadable("the JSON object must be str, bytes or bytearray, not int"), + ), + ( + # Valid JSON, nested deeper than Python's parser can follow. + {"json": "[" * 100_000 + "]" * 100_000}, ( - "TypeError: The browser sent a malformed result: the JSON object " - "must be str, bytes or bytearray, not int" + "The script returned a value nested too deeply for Python's JSON " + "parser. Return a value with fewer levels of nested objects and " + "arrays." ), ), ], ) -async def test_a_malformed_result_raises_a_serialization_error( +async def test_a_result_the_backend_cannot_read_raises_a_serialization_error( outcome: dict[str, Any], expected: str ): - """A result without valid JSON fails the call instead of hanging it. + """A result the backend cannot parse fails the call instead of hanging it. Args: - outcome: The malformed outcome. + outcome: The outcome the browser sent. expected: The error's message. """ calls = BrowserCalls() _, task, rid = await _start_call(calls) - calls.resolve("tok", rid, outcome) + calls.resolve(rid, outcome) with pytest.raises(BrowserResultSerializationError) as exc_info: await task - assert str(exc_info.value) == expected + exc = exc_info.value + assert (exc.name, exc.message, exc.stack, str(exc)) == ("", expected, "", expected) + _assert_forgotten(calls) async def test_call_times_out(): """A call without a result within its timeout raises TimeoutError and is forgotten.""" calls = BrowserCalls() with pytest.raises(TimeoutError) as exc_info: - await calls.call("tok", EVENT, 0.01, Browser().emit) + await calls.call("tok", "p1", EVENT, 0.01, Browser().emit) assert str(exc_info.value) == ( - "The browser did not return a result for `_call_script` within 0.01 seconds." + "The browser did not return a result for `_call_script` within 0.01 " + "seconds. If the script needs longer, pass a longer `timeout=` to the " + "call (or `timeout=None` to wait without a limit) or raise " + "`browser_call_timeout` in rxconfig.py; if it returns a promise, make " + "sure the promise settles." ) - assert calls._pending == {} + _assert_forgotten(calls) -async def test_disconnect_fails_the_calls_after_the_grace_period(): - """A tab that does not reconnect within the grace period fails its calls.""" +async def test_disconnect_fails_every_call_of_the_tab_after_the_grace_period(): + """A tab that does not reconnect within the grace period fails all its calls.""" calls = BrowserCalls() - _, task, _ = await _start_call(calls) + _, first, _ = await _start_call(calls) + _, second, _ = await _start_call(calls) + _, other_tab, other_rid = await _start_call(calls, token="other") calls.disconnect("tok", 0.01) - with pytest.raises(BrowserDisconnectedError) as exc_info: - await task - assert str(exc_info.value) == ( - "The browser tab disconnected before returning a result." - ) - assert calls._pending == {} - assert calls._grace_timers == {} + failed = (BrowserDisconnectedError, grace_expired(0.01)) + assert [await _raised(first), await _raised(second)] == [failed, failed] + assert calls._tabs.keys() == {"other"} + calls.resolve(other_rid, {"json": "1"}) + assert await other_tab == 1 + _assert_forgotten(calls) async def test_disconnect_without_a_grace_period_fails_the_calls_at_once(): @@ -212,52 +294,98 @@ async def test_disconnect_without_a_grace_period_fails_the_calls_at_once(): calls = BrowserCalls() _, task, _ = await _start_call(calls) calls.disconnect("tok", 0) - assert calls._grace_timers == {} - with pytest.raises(BrowserDisconnectedError): - await task + assert calls._tabs == {} + assert await _raised(task) == (BrowserDisconnectedError, grace_expired(0)) + _assert_forgotten(calls) + + +async def test_a_result_that_came_before_the_disconnect_is_kept(): + """A call settled just before its tab disconnects returns its result.""" + calls = BrowserCalls() + _, task, rid = await _start_call(calls) + calls.resolve(rid, {"json": "7"}) + calls.disconnect("tok", 0) + assert await task == 7 + _assert_forgotten(calls) -async def test_reconnect_within_the_grace_period_keeps_the_calls(): - """A tab reconnecting in time still answers its calls.""" +async def test_a_reconnect_of_the_page_within_the_grace_period_keeps_the_calls(): + """The same page load reconnecting in time still answers its calls.""" calls = BrowserCalls() _, task, rid = await _start_call(calls) calls.disconnect("tok", 0.01) - calls.reconnect("tok") - assert calls._grace_timers == {} + timer = calls._tabs["tok"].grace_timer + calls.connect("tok", "p1") + assert timer is not None + assert timer.cancelled() + assert calls._tabs["tok"].grace_timer is None await asyncio.sleep(0.02) assert not task.done() - calls.resolve("tok", rid, {"json": "true"}) + calls.resolve(rid, {"json": "true"}) assert await task is True + _assert_forgotten(calls) -def test_disconnect_without_pending_calls_starts_no_timer(): - """A tab with nothing pending needs no grace period.""" +async def test_a_connect_from_another_page_load_fails_the_calls_at_once(): + """A reloaded page connecting under the token means the script stopped with the old one.""" calls = BrowserCalls() + _, task, _ = await _start_call(calls) calls.disconnect("tok", 5) - assert calls._grace_timers == {} + timer = calls._tabs["tok"].grace_timer + calls.connect("tok", "p2") + assert timer is not None + assert timer.cancelled() + assert await _raised(task) == (BrowserDisconnectedError, PAGE_REPLACED) + _assert_forgotten(calls) -async def test_settled_call_ends_the_grace_period(): - """The last call settling during the grace period cancels its timer.""" +async def test_a_connect_while_the_tab_is_connected_keeps_its_calls(): + """A connect for a tab that never disconnected, or one without calls, changes nothing.""" calls = BrowserCalls() _, task, rid = await _start_call(calls) - calls.disconnect("tok", 5) - timer = calls._grace_timers["tok"] - calls.resolve("tok", rid, {"json": "1"}) + calls.connect("tok", "p2") + calls.connect("unknown", "p1") + calls.disconnect("unknown", 5) + assert calls._tabs.keys() == {"tok"} + calls.resolve(rid, {"json": "1"}) assert await task == 1 - assert calls._grace_timers == {} + _assert_forgotten(calls) + + +async def test_a_call_ending_during_the_grace_period_cancels_its_timer(): + """The last call settling, or its task cancelled, while the tab is away ends the grace period.""" + calls = BrowserCalls() + _, settled, rid = await _start_call(calls) + calls.disconnect("tok", 5) + timer = calls._tabs["tok"].grace_timer + calls.resolve(rid, {"json": "1"}) + assert await settled == 1 + assert timer is not None + assert timer.cancelled() + _assert_forgotten(calls) + + _, cancelled, _ = await _start_call(calls) + calls.disconnect("tok", 5) + timer = calls._tabs["tok"].grace_timer + cancelled.cancel() + with pytest.raises(asyncio.CancelledError): + await cancelled + assert timer is not None assert timer.cancelled() + _assert_forgotten(calls) async def test_close_cancels_pending_calls(): - """Shutting the backend down cancels the calls still waiting.""" + """Shutting the backend down cancels the calls still waiting, and their timers.""" calls = BrowserCalls() - _, task, _ = await _start_call(calls) + _, away, _ = await _start_call(calls) calls.disconnect("tok", 5) - timer = calls._grace_timers["tok"] + timer = calls._tabs["tok"].grace_timer + _, connected, _ = await _start_call(calls, token="other") calls.close() - with pytest.raises(asyncio.CancelledError): - await task + for task in (away, connected): + with pytest.raises(asyncio.CancelledError): + await task + assert timer is not None assert timer.cancelled() - assert calls._pending == {} - assert calls._grace_timers == {} + _assert_forgotten(calls) diff --git a/tests/units/reflex_base/event/processor/test_event_processor.py b/tests/units/reflex_base/event/processor/test_event_processor.py index d811eed7b2f..86309af949d 100644 --- a/tests/units/reflex_base/event/processor/test_event_processor.py +++ b/tests/units/reflex_base/event/processor/test_event_processor.py @@ -31,6 +31,10 @@ from reflex.event import Event, EventHandler, EventSpec from tests.units.conftest import active_tracer +from tests.units.reflex_base.event.processor.test_browser_calls import ( + PAGE_REPLACED, + grace_expired, +) # Module-level log so event handlers can record what happened. _CALL_LOG: list[dict[str, Any]] = [] @@ -2170,26 +2174,26 @@ def _returns_future() -> asyncio.Future[int]: class _FakeEventNamespace: """Records the updates sent to the clients it reports as connected.""" - def __init__(self, *connected: str): + def __init__(self, **pages: str): """Connect the given tokens. Args: - connected: The connected client tokens. + pages: The page load each connected client token connected from. """ - self.connected = set(connected) + self.pages = pages self.updates: list[tuple[str, Any]] = [] self.sent = asyncio.Event() - def _is_connected(self, token: str) -> bool: - """Whether a client is connected. + def _page_of(self, token: str) -> str | None: + """Get the page load of a connected client. Args: token: The client token. Returns: - Whether the token is connected. + The page id, or None when the token is not connected. """ - return token in self.connected + return self.pages.get(token) async def emit_update(self, update: Any, token: str) -> None: """Record an update sent to a client. @@ -2218,14 +2222,15 @@ async def test_call_frontend_sends_the_event_and_awaits_its_result( """The configured call_frontend sends the event with a rid and resolves with the result. Calls to a tab that is not connected fail at once; a tab disconnecting - fails its calls after the grace period unless it reconnects; stopping - the processor cancels the calls still waiting. + fails its calls after the grace period unless its page reconnects, and at + once when another page load connects; stopping the processor cancels the + calls still waiting. Args: processor: The event processor fixture. """ event = Event(name="_call_script", payload={"javascript_code": "1"}) - namespace = _FakeEventNamespace("tok") + namespace = _FakeEventNamespace(tok="p1") processor.browser_call_grace_period = 0.01 processor.configure(event_namespace=namespace) # pyright: ignore[reportArgumentType] assert processor._root_context is not None @@ -2235,7 +2240,11 @@ async def test_call_frontend_sends_the_event_and_awaits_its_result( with pytest.raises(BrowserDisconnectedError) as exc_info: await processor._root_context.fork(token="gone").call_frontend(event, 1) assert str(exc_info.value) == ( - "The browser tab is not connected, so `_call_script` cannot run in it." + "`_call_script` cannot run in the browser tab: the tab is not " + "connected to this backend worker, because it was closed, is " + "reconnecting, or reconnected to another worker. Catch " + "BrowserDisconnectedError where the tab may be gone; with several " + "backend workers, route each tab to one worker (sticky sessions)." ) answered = asyncio.create_task(ctx.call_frontend(event, 1)) @@ -2243,18 +2252,26 @@ async def test_call_frontend_sends_the_event_and_awaits_its_result( assert [(token, update.events) for token, update in namespace.updates] == [ ("tok", [dataclasses.replace(event, payload={**event.payload, "rid": rid})]) ] - # Reconnecting within the grace period keeps the call. processor._on_disconnect("tok") - processor._on_connect("tok") + processor._on_connect("tok", "p1") await asyncio.sleep(0.02) - processor._browser_calls.resolve("tok", rid, {"json": "[1]"}) + processor._browser_calls.resolve(rid, {"json": "[1]"}) assert await answered == [1] abandoned = asyncio.create_task(ctx.call_frontend(event, 1)) await namespace.next_rid() processor._on_disconnect("tok") - with pytest.raises(BrowserDisconnectedError): + with pytest.raises(BrowserDisconnectedError) as exc_info: await abandoned + assert str(exc_info.value) == grace_expired(0.01) + + reloaded = asyncio.create_task(ctx.call_frontend(event, 1)) + await namespace.next_rid() + processor._on_disconnect("tok") + processor._on_connect("tok", "p2") + with pytest.raises(BrowserDisconnectedError) as exc_info: + await reloaded + assert str(exc_info.value) == PAGE_REPLACED pending = asyncio.create_task(ctx.call_frontend(event, None)) await namespace.next_rid() diff --git a/tests/units/test_app.py b/tests/units/test_app.py index 463dc8d157e..3021ea6170a 100644 --- a/tests/units/test_app.py +++ b/tests/units/test_app.py @@ -37,7 +37,7 @@ from reflex_base.constants.state import FIELD_MARKER from reflex_base.event import Event, EventSpec from reflex_base.event.context import EventContext -from reflex_base.event.processor import BaseStateEventProcessor +from reflex_base.event.processor import BaseStateEventProcessor, EventProcessor from reflex_base.event.processor.event_processor import QueueShutDown from reflex_base.plugins import CompileContext, CompilerHooks, PageContext, Plugin from reflex_base.registry import RegistrationContext @@ -5661,34 +5661,41 @@ def test_result_event_matches_handler_and_frontend(): assert frontend_name == constants.SocketEvent.RESULT +def test_connect_page_key_matches_frontend(): + """The page id rides in the CONNECT auth packet under the key on_connect reads.""" + state_js = (Templates.Dirs.WEB_TEMPLATE / "utils/state.js").read_text() + assert re.findall(r"^ {6}(\w+): PAGE_ID,$", state_js, re.MULTILINE) == [ + constants.CompileVars.CONNECT_AUTH_PAGE + ] + + @pytest.mark.asyncio -async def test_on_result_settles_the_call_of_the_sending_token( +async def test_on_result_settles_a_call_by_its_request_id( event_namespace_with_processor_mock: EventNamespace, ): - """A result resolves the sending tab's call; a malformed or unknown one is dropped. + """A result goes to the call with its rid from any socket; a malformed one is dropped. Args: event_namespace_with_processor_mock: Namespace with a mocked processor. """ namespace = event_namespace_with_processor_mock - namespace._token_manager.sid_to_token["sid1"] = "token" resolve = cast(Mock, namespace.app.event_processor._browser_calls.resolve) outcome = {"rid": "r1", "json": "1"} - await namespace.on_result("sid1", outcome) - resolve.assert_called_once_with("token", "r1", outcome) + # The tab may have been given a new token since, so the sid is not consulted. + await namespace.on_result("unknown-sid", outcome) + resolve.assert_called_once_with("r1", outcome) resolve.reset_mock() - await namespace.on_result("unknown-sid", outcome) await namespace.on_result("sid1") await namespace.on_result("sid1", ["r1"]) await namespace.on_result("sid1", {"rid": 1, "json": "1"}) resolve.assert_not_called() -def test_is_connected_only_for_a_socket_on_this_instance( +def test_page_of_only_for_a_live_socket_on_this_instance( event_namespace_with_processor_mock: EventNamespace, ): - """Browser calls go only to a tab whose socket is connected to this instance. + """Browser calls go only to a tab whose socket is live on this instance. Args: event_namespace_with_processor_mock: Namespace with a mocked processor. @@ -5699,34 +5706,96 @@ def test_is_connected_only_for_a_socket_on_this_instance( instance_id=manager.instance_id, sid="sid1" ) manager.token_to_socket["remote"] = SocketRecord(instance_id="other", sid="sid2") - assert [ - namespace._is_connected(token) for token in ("local", "remote", "missing") - ] == [True, False, False] + namespace._sid_pages["sid1"] = "p1" + assert [namespace._page_of(token) for token in ("local", "remote", "missing")] == [ + "p1", + None, + None, + ] + # A socket that disconnected has no page, before its token is unlinked. + namespace.on_disconnect("sid1") + assert namespace._page_of("local") is None -@pytest.mark.asyncio -@pytest.mark.parametrize("duplicate", [False, True]) -async def test_link_token_to_sid_ends_the_grace_period_of_a_reconnecting_tab( - event_namespace_with_processor_mock: EventNamespace, - duplicate: bool, -): - """A tab reconnecting under its token keeps its browser calls; a new tab does not. +async def _start_browser_call( + namespace: EventNamespace, ctx: EventContext +) -> tuple[asyncio.Task[Any], str]: + """Start an awaited browser call and wait for its event to reach the socket. Args: - event_namespace_with_processor_mock: Namespace with a mocked processor. - duplicate: Whether the token is a duplicate, so the tab gets a new one. - """ - namespace = event_namespace_with_processor_mock - namespace._token_manager.link_token_to_sid = AsyncMock( - return_value="new-token" if duplicate else None + namespace: The namespace the event is emitted on. + ctx: The client's event context. + + Returns: + The task awaiting the call, and its request id. + """ + sent = asyncio.Event() + emit = cast(AsyncMock, namespace.emit) + emit.reset_mock(side_effect=True) + emit.side_effect = lambda *_args, **_kwargs: sent.set() + task = asyncio.create_task( + ctx.call_frontend(Event(name="_call_script", payload={}), None) ) + await sent.wait() + (update,) = [call.args[1] for call in emit.await_args_list] + return task, update.events[0].payload["rid"] + + +@pytest.mark.asyncio +async def test_browser_calls_follow_their_page_across_socket_connects(): + """An awaited call survives its page reconnecting, and fails at once when the page is gone. + + The socket's connect and disconnect handlers tell the event processor + which page load each token's socket belongs to. + """ + app = App() + namespace = EventNamespace("/event", app) + namespace._token_manager = LocalTokenManager() namespace.emit = AsyncMock() - await namespace.link_token_to_sid("sid1", "token", update_state=False) - on_connect = cast(Mock, namespace.app.event_processor._on_connect) - if duplicate: - on_connect.assert_not_called() - else: - on_connect.assert_called_once_with("token") + processor = app._event_processor = EventProcessor(browser_call_grace_period=5) + processor.configure(event_namespace=namespace) + assert processor._root_context is not None + ctx = processor._root_context.fork(token="tok") + environ = {"QUERY_STRING": "token=tok"} + not_connected = ( + "`_call_script` cannot run in the browser tab: the tab is not connected " + "to this backend worker, because it was closed, is reconnecting, or " + "reconnected to another worker. Catch BrowserDisconnectedError where " + "the tab may be gone; with several backend workers, route each tab to " + "one worker (sticky sessions)." + ) + + async with processor: + await namespace.on_connect("sid1", environ, {"page": "p1"}) + reconnected, rid = await _start_browser_call(namespace, ctx) + cleanup = namespace.on_disconnect("sid1") + # A call made as the socket drops fails at once, before its token is + # unlinked. + with pytest.raises(exceptions.BrowserDisconnectedError) as exc_info: + await ctx.call_frontend(Event(name="_call_script", payload={}), None) + assert str(exc_info.value) == not_connected + # Another tab connecting with the token before then is a duplicate, + # given a new token: it does not fail the first tab's call. + await namespace.on_connect("dup", environ, {"page": "p9"}) + assert cleanup is not None + await cleanup + await namespace.on_connect("sid2", environ, {"page": "p1"}) + await namespace.on_result("sid2", {"rid": rid, "json": "1"}) + assert await reconnected == 1 + + reloaded, _ = await _start_browser_call(namespace, ctx) + cleanup = namespace.on_disconnect("sid2") + assert cleanup is not None + await cleanup + await namespace.on_connect("sid3", environ, {"page": "p2"}) + with pytest.raises(exceptions.BrowserDisconnectedError) as exc_info: + await reloaded + assert str(exc_info.value) == ( + "The browser tab reloaded or left the page before the script returned " + "a result, so the script stopped. Catch BrowserDisconnectedError where " + "the user may reload or leave the page while the script runs." + ) + assert processor._browser_calls._tabs == {} @pytest.mark.asyncio From 5916a61dfa9a0a3690568565509f3cc1b17ae601 Mon Sep 17 00:00:00 2001 From: Farhan Date: Sat, 21 Nov 2026 21:31:22 +0000 Subject: [PATCH 12/13] Test awaited browser calls across dropped sockets and reloads The CallScript app drops its socket and reconnects within the grace period (the result still arrives), past it (BrowserDisconnectedError), and reloads the page (BrowserDisconnectedError at once). A vitest covers a script dispatching events through the late-bound addEvents. Claude-Session: https://claude.ai/code/session_01LwJUCVxPh3ihrnaFn6CWnf --- .../reflex-frontend/tests/run_script.test.js | 8 ++ .../tests_playwright/test_call_script.py | 121 ++++++++++++++++-- 2 files changed, 118 insertions(+), 11 deletions(-) diff --git a/packages/reflex-frontend/tests/run_script.test.js b/packages/reflex-frontend/tests/run_script.test.js index 2cae6939269..da6bc841d58 100644 --- a/packages/reflex-frontend/tests/run_script.test.js +++ b/packages/reflex-frontend/tests/run_script.test.js @@ -37,6 +37,14 @@ describe("_call_script", () => { expect(args).toEqual([42]); }); + test("a script dispatches events through the late-bound addEvents", async () => { + eventLoop.addEvents = vi.fn(); + await callScript('addEvents([ReflexEvent("state.go", {n: 1})], [2], {})'); + expect(eventLoop.addEvents.mock.calls).toEqual([ + [[{ name: "state.go", payload: { n: 1 } }], [2], {}], + ]); + }); + test("runs strict and sees no other module-local names", async () => { const onerror = vi.fn(); window.onerror = onerror; diff --git a/tests/integration/tests_playwright/test_call_script.py b/tests/integration/tests_playwright/test_call_script.py index 5526150a6d8..8fc15ea4588 100644 --- a/tests/integration/tests_playwright/test_call_script.py +++ b/tests/integration/tests_playwright/test_call_script.py @@ -9,6 +9,10 @@ from reflex.testing import AppHarness +# Seconds an awaited call waits for its tab to reconnect, short for the tests +# that wait it out. +GRACE_PERIOD = 2.0 + def CallScript(): """A test app for browser javascript integration.""" @@ -16,6 +20,7 @@ def CallScript(): import reflex as rx from reflex.utils.exceptions import ( + BrowserDisconnectedError, BrowserResultSerializationError, BrowserScriptError, ) @@ -75,12 +80,17 @@ async def await_results(self): @rx.event(background=True) async def await_user(self): - # Settled by the test once another event has gone through. - answer = await rx.call_script( - "new Promise((resolve) => { window.answerAwaited = resolve })" - ) + # Settled by the test, which may first drop the socket or reload. + try: + answer = repr( + await rx.call_script( + "new Promise((resolve) => { window.answerAwaited = resolve })" + ) + ) + except BrowserDisconnectedError as e: + answer = f"BrowserDisconnectedError: {e}" async with self: - self.awaited = [repr(answer)] + self.awaited = [answer] @rx.event def call_script_callback(self, result): @@ -337,6 +347,14 @@ def index(): rx.button( "await_user", on_click=CallScriptState.await_user, id="await_user" ), + rx.button( + "drop_connection", + on_click=rx.call_script( + "socket.disconnect();" + "setTimeout(() => socket.connect(), window.reconnectAfterMs)" + ), + id="drop_connection", + ), rx.button( "set_value_busy", on_click=CallScriptState.set_value("busy"), @@ -423,11 +441,13 @@ def call_script(tmp_path_factory) -> Generator[AppHarness, None, None]: Yields: running AppHarness instance """ - with AppHarness.create( - root=tmp_path_factory.mktemp("call_script"), - app_source=CallScript, - ) as harness: - yield harness + with pytest.MonkeyPatch.context() as monkeypatch: + monkeypatch.setenv("REFLEX_BROWSER_CALL_GRACE_PERIOD", str(GRACE_PERIOD)) + with AppHarness.create( + root=tmp_path_factory.mktemp("call_script"), + app_source=CallScript, + ) as harness: + yield harness @pytest.fixture @@ -603,7 +623,10 @@ def test_await_call_script(call_script: AppHarness, call_script_page: Page): ), ( "TimeoutError: The browser did not return a result for `_call_script` " - "within 0.5 seconds." + "within 0.5 seconds. If the script needs longer, pass a longer " + "`timeout=` to the call (or `timeout=None` to wait without a limit) or " + "raise `browser_call_timeout` in rxconfig.py; if it returns a promise, " + "make sure the promise settles." ), ) call_script_page.locator("#await_results").click() @@ -629,3 +652,79 @@ def test_awaited_script_does_not_hold_up_other_events( expect(call_script_page.locator("#value")).to_have_text("busy") call_script_page.evaluate("window.answerAwaited({answer: 'yes'})") expect(call_script_page.locator("#awaited")).to_have_value("{'answer': 'yes'}") + + +def _await_user(page: Page) -> None: + """Start the awaited script that waits for the test to answer. + + Args: + page: Playwright page. + """ + page.locator("#await_user").click() + page.wait_for_function("() => typeof window.answerAwaited === 'function'") + + +def _drop_connection(page: Page, reconnect_after_ms: int) -> None: + """Drop the tab's socket and connect it again after a delay. + + Args: + page: Playwright page. + reconnect_after_ms: Milliseconds until the socket connects again. + """ + page.evaluate(f"window.reconnectAfterMs = {reconnect_after_ms}") + page.locator("#drop_connection").click() + + +def test_awaited_result_arrives_after_a_reconnect_within_the_grace_period( + call_script: AppHarness, call_script_page: Page +): + """A result sent while the socket is down reaches the backend once it reconnects in time. + + Args: + call_script: harness for CallScript app. + call_script_page: Playwright page. + """ + _await_user(call_script_page) + _drop_connection(call_script_page, 300) + call_script_page.evaluate("window.answerAwaited('after the drop')") + expect(call_script_page.locator("#awaited")).to_have_value("'after the drop'") + + +def test_awaited_call_fails_when_the_tab_stays_away_past_the_grace_period( + call_script: AppHarness, call_script_page: Page +): + """A tab that reconnects only after the grace period has its call failed. + + Args: + call_script: harness for CallScript app. + call_script_page: Playwright page. + """ + _await_user(call_script_page) + _drop_connection(call_script_page, int(GRACE_PERIOD * 1000) + 1500) + expect(call_script_page.locator("#awaited")).to_have_value( + "BrowserDisconnectedError: The browser tab disconnected and did not " + f"reconnect within browser_call_grace_period ({GRACE_PERIOD} seconds), so " + "the script's result is lost: the tab was closed, or lost its connection. " + "Catch BrowserDisconnectedError where the user may close the tab, or raise " + "`browser_call_grace_period` in rxconfig.py if connections drop for longer.", + timeout=10_000, + ) + + +def test_awaited_call_fails_at_once_when_the_page_reloads( + call_script: AppHarness, call_script_page: Page +): + """Reloading the page stops the script, so the call fails without waiting out the grace period. + + Args: + call_script: harness for CallScript app. + call_script_page: Playwright page. + """ + _await_user(call_script_page) + call_script_page.reload() + expect(call_script_page.locator("#awaited")).to_have_value( + "BrowserDisconnectedError: The browser tab reloaded or left the page " + "before the script returned a result, so the script stopped. Catch " + "BrowserDisconnectedError where the user may reload or leave the page " + "while the script runs." + ) From 7bd31a08270f24fb9d46cb4eba1aed52a1063ca3 Mon Sep 17 00:00:00 2001 From: Farhan Date: Sat, 21 Nov 2026 21:32:44 +0000 Subject: [PATCH 13/13] Document the errors of awaited browser calls and their fixes The Awaiting Results section now lists the rules, then each error with its exact message and fix, and says a reload fails the call at once. The configuration page shows the settings in rxconfig.py and that browser_call_timeout may be None. Claude-Session: https://claude.ai/code/session_01LwJUCVxPh3ihrnaFn6CWnf --- docs/advanced_onboarding/configuration.md | 14 +++- docs/api-reference/browser_javascript.md | 79 +++++++++++++------ news/+await-browser-results.feature.md | 2 +- .../news/+await-browser-results.feature.md | 2 +- 4 files changed, 69 insertions(+), 28 deletions(-) diff --git a/docs/advanced_onboarding/configuration.md b/docs/advanced_onboarding/configuration.md index c55ef3b478a..21b6f8cf67d 100644 --- a/docs/advanced_onboarding/configuration.md +++ b/docs/advanced_onboarding/configuration.md @@ -50,10 +50,18 @@ The setting can also be overridden with `REFLEX_EVENT_LOOP_BLOCKING_THRESHOLD`, A background event handler can [await the result of a browser script](/docs/api-reference/browser-javascript/#awaiting-results). Two settings bound how long it waits: -- `browser_call_timeout` (default `30.0`): the seconds an awaited call waits for its result before raising `TimeoutError`. A call can override it with `timeout=`. -- `browser_call_grace_period` (default `5.0`): the seconds an awaited call waits for its tab to reconnect after a disconnect before raising `BrowserDisconnectedError`. +```python +config = rx.Config( + app_name="my_app", + browser_call_timeout=60.0, + browser_call_grace_period=10.0, +) +``` + +- `browser_call_timeout` (default `30.0`): the seconds an awaited call waits for its result before raising `TimeoutError`, or `None` to wait without a limit. A call can override it with `timeout=`. +- `browser_call_grace_period` (default `5.0`): the seconds an awaited call waits for its tab to reconnect after a disconnect before raising `BrowserDisconnectedError`. A reloaded page fails its calls at once. -They can also be set with `REFLEX_BROWSER_CALL_TIMEOUT` and `REFLEX_BROWSER_CALL_GRACE_PERIOD`. +They can also be set in seconds with `REFLEX_BROWSER_CALL_TIMEOUT` and `REFLEX_BROWSER_CALL_GRACE_PERIOD`. Waiting without a limit is set in `rxconfig.py`. ## Environment Variables diff --git a/docs/api-reference/browser_javascript.md b/docs/api-reference/browser_javascript.md index 6825e18fa66..93edbb0924c 100644 --- a/docs/api-reference/browser_javascript.md +++ b/docs/api-reference/browser_javascript.md @@ -144,9 +144,8 @@ If the callback is None, then no event is triggered. ## Awaiting Results A [background event handler](/docs/events/background-events/) can `await` `rx.call_script`, `rx.call_function`, or -`rx.run_script` to get the result directly, instead of passing a callback. The handler continues once the browser sends -the value back, so the code that asks for a value and the code that uses it stay together. If the script returns a -promise, the handler gets the value the promise resolves to. +`rx.run_script` to get the script's result directly, instead of passing a callback. If the script returns a promise, the +handler gets the value the promise resolves to. ```python demo exec class ViewportState(rx.State): @@ -166,32 +165,66 @@ def viewport_demo(): ) ``` -The result travels as JSON: objects become `dict`, arrays become `list`, and `undefined` becomes `None`. Return the -data you need from a DOM element rather than the element itself. +The rules: -Await the call outside `async with self`. While the handler holds the state lock, the tab's other events would have to -wait for the browser's answer, so awaiting there raises an error. For the same reason, a regular event handler cannot -await a script. Pass either `callback=` or `await` the result, not both. - -The awaited call raises an exception when no value comes back. The Reflex exceptions are imported from -`reflex.utils.exceptions`: - -- `BrowserScriptError` if the script throws, or the promise it returns is rejected. The exception - carries the Javascript error's `name`, `message` and `stack`. -- `BrowserResultSerializationError` (a subclass of `BrowserScriptError`) if the value cannot be - sent as JSON. -- `TimeoutError` if no result arrives within the timeout. The timeout defaults to `browser_call_timeout` in - `rxconfig.py` (30 seconds). Pass `timeout=` to a single call to override it, or `timeout=None` to wait as long as it - takes: +- Await the call in a background handler, outside `async with self`. While a handler holds the state lock, the tab's + other events would wait for the browser's answer, so a regular handler cannot await a script either. +- Pass either `callback=` or `await` the result, not both. +- The result travels as JSON: objects become `dict`, arrays become `list`, and `undefined` becomes `None`. Return the + data you need from a DOM element, not the element itself. +- A call waits `browser_call_timeout` seconds for its result (30 by default, set in `rxconfig.py`). Pass `timeout=` to + one call to change it, or `timeout=None` to wait without a limit: ```python answer = await rx.call_script("askTheUser()", timeout=None) ``` -- `BrowserDisconnectedError` (a `ConnectionError`) if the tab is not connected when the call is - made. The same error is raised if the tab disconnects and does not reconnect within `browser_call_grace_period` - (5 seconds). A tab that reconnects in time still delivers its result. A tab that reloads loses the running script, so the - call ends at its timeout. +- The script keeps running while the tab's socket reconnects. A tab that reconnects within `browser_call_grace_period` + seconds (5 by default) still delivers its result. A tab that is closed, reloaded or navigated away stops the script, + and the call fails. + +The exceptions are imported from `reflex.utils.exceptions`: + +```python +from reflex.utils.exceptions import BrowserDisconnectedError, BrowserScriptError +``` + +Each error below gives its exact message, with the values of an example call, and its fix. + +- `BrowserScriptError`: the script throws, or the promise it returns is rejected. It carries the Javascript error's + `name`, `message` and `stack`, and reads like the browser console: ``ReferenceError: missing_function is not + defined``. Fix the script, or catch the error. +- `BrowserResultSerializationError`, a subclass of `BrowserScriptError`: the result cannot reach the backend as JSON. + - ``TypeError: The script returned a DOM node or window, which JSON cannot carry; return the data you need from it + instead.`` + - ``TypeError: The script returned a function, which JSON cannot carry; return plain data (objects, arrays, strings, + numbers, booleans or null) instead.`` (also for a symbol) + - ``The script returned a value nested too deeply for Python's JSON parser. Return a value with fewer levels of + nested objects and arrays.`` + - ``The browser sent a result the backend cannot read (...). The page runs a frontend built for another version of + Reflex: rebuild the frontend (restart `reflex run`, or export the app again) and reload the page.`` +- `TimeoutError`: ``The browser did not return a result for `_call_script` within 30.0 seconds. If the script needs + longer, pass a longer `timeout=` to the call (or `timeout=None` to wait without a limit) or raise + `browser_call_timeout` in rxconfig.py; if it returns a promise, make sure the promise settles.`` +- `BrowserDisconnectedError`, a `ConnectionError`: the tab cannot return the result. + - When the call is made: `` `_call_script` cannot run in the browser tab: the tab is not connected to this backend + worker, because it was closed, is reconnecting, or reconnected to another worker. Catch BrowserDisconnectedError + where the tab may be gone; with several backend workers, route each tab to one worker (sticky sessions). `` + - After the grace period: ``The browser tab disconnected and did not reconnect within browser_call_grace_period (5.0 + seconds), so the script's result is lost: the tab was closed, or lost its connection. Catch + BrowserDisconnectedError where the user may close the tab, or raise `browser_call_grace_period` in rxconfig.py if + connections drop for longer.`` + - As soon as a reloaded page connects: ``The browser tab reloaded or left the page before the script returned a + result, so the script stopped. Catch BrowserDisconnectedError where the user may reload or leave the page while + the script runs.`` + - Without a frontend, for example in a test: `` `_call_script` cannot run in a browser: the app is running without a + frontend connection (for example in a test, or a process that runs only the backend), so no tab can return a + result. Await browser scripts in handlers triggered from a page of the running app, and catch + BrowserDisconnectedError where no page may be connected. `` +- `EventHandlerTypeError`: + - `` `_call_script` cannot be awaited while the state lock is held, as every other event of this tab would wait for + the browser's answer; await it in a background event handler, outside `async with self`. `` + - `` `_call_script` was given a callback and awaited; pass either callback= or await its result, not both. `` ```md alert info # Awaiting results with multiple backend workers diff --git a/news/+await-browser-results.feature.md b/news/+await-browser-results.feature.md index 574ca0e7e6c..7442e9b99e2 100644 --- a/news/+await-browser-results.feature.md +++ b/news/+await-browser-results.feature.md @@ -1 +1 @@ -The backend now receives the results of browser scripts that a background event handler awaits (`await rx.call_script(...)`), and keeps those calls alive while their tab reconnects. +The backend receives the results of browser scripts that a background event handler awaits (`await rx.call_script(...)`), keeps those calls alive while their tab reconnects, and fails them with `BrowserDisconnectedError` as soon as the page reloads. diff --git a/packages/reflex-base/news/+await-browser-results.feature.md b/packages/reflex-base/news/+await-browser-results.feature.md index 1b245a63682..1f906cecf3b 100644 --- a/packages/reflex-base/news/+await-browser-results.feature.md +++ b/packages/reflex-base/news/+await-browser-results.feature.md @@ -8,4 +8,4 @@ async def measure(self): self.width = size["w"] ``` -A script error raises `BrowserScriptError`, and a missing result raises `TimeoutError` (`browser_call_timeout` config, or `timeout=` per call). A tab that disconnects and does not reconnect within `browser_call_grace_period` raises `BrowserDisconnectedError`. See [Awaiting Results](https://reflex.dev/docs/api-reference/browser-javascript/#awaiting-results). +A script error raises `BrowserScriptError`, a missing result `TimeoutError` (`browser_call_timeout` in `rxconfig.py`, or `timeout=` per call), and a tab that is closed, reloaded or away longer than `browser_call_grace_period` raises `BrowserDisconnectedError`. See [Awaiting Results](https://reflex.dev/docs/api-reference/browser-javascript/#awaiting-results).