diff --git a/docs/advanced_onboarding/configuration.md b/docs/advanced_onboarding/configuration.md index 390f0ba6d33..21b6f8cf67d 100644 --- a/docs/advanced_onboarding/configuration.md +++ b/docs/advanced_onboarding/configuration.md @@ -46,6 +46,23 @@ 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: + +```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 in seconds with `REFLEX_BROWSER_CALL_TIMEOUT` and `REFLEX_BROWSER_CALL_GRACE_PERIOD`. Waiting without a limit is set in `rxconfig.py`. + ## 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..93edbb0924c 100644 --- a/docs/api-reference/browser_javascript.md +++ b/docs/api-reference/browser_javascript.md @@ -141,6 +141,99 @@ 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 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): + 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 rules: + +- 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) + ``` + +- 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 + +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..7442e9b99e2 --- /dev/null +++ b/news/+await-browser-results.feature.md @@ -0,0 +1 @@ +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 new file mode 100644 index 00000000000..1f906cecf3b --- /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`, 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). diff --git a/packages/reflex-base/src/reflex_base/config.py b/packages/reflex-base/src/reflex_base/config.py index bdd66072f6d..ce8a373f9dd 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, 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. """ app_name: str @@ -300,6 +302,10 @@ class BaseConfig: event_loop_blocking_threshold: float = 0.2 + browser_call_timeout: float | None = 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/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/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..4f847f2345c 100644 --- a/packages/reflex-base/src/reflex_base/event/__init__.py +++ b/packages/reflex-base/src/reflex_base/event/__init__.py @@ -2083,29 +2083,90 @@ 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. + + 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 _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 an awaited call waits for the result. + **kwargs: The script, under the name the frontend reads it from. + + Returns: + The spec of the script event. + """ + 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]) + ), + ) + return _BrowserCallSpec(handler=spec.handler, args=spec.args, timeout=timeout) + + 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 = ( @@ -2116,59 +2177,56 @@ 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", - inspect.signature(call_script), - javascript_code=javascript_code, - **callback_kwargs, + return _browser_call_spec( + "_call_script", call_script, callback, timeout, javascript_code=javascript_code ) 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 ) - return server_side( - "_call_function", - inspect.signature(call_function), - function=javascript_code, - **callback_kwargs, + return _browser_call_spec( + "_call_function", call_function, callback, timeout, function=javascript_code ) 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 +2235,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): @@ -3563,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/context.py b/packages/reflex-base/src/reflex_base/event/context.py index 6cb4624dd51..d91378ddaa7 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,10 @@ class EventContext(BaseContext): emit_event_impl: EmitEventProtocol | None = dataclasses.field( default=None, repr=False ) + # 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 +183,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 +262,31 @@ 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 = ( + 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) + 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..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 @@ -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, @@ -27,16 +28,18 @@ Event, EventHandler, EventSpec, + _BrowserCallSpec, _is_bound_event_handler, ) from reflex_base.event.context import EventContext 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 -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__) @@ -577,6 +580,43 @@ def ensure_locked( return None +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. + + 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) + 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) + if isinstance(timeout, Unset): + timeout = 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 +625,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 +660,8 @@ async def execute_event_inline(spec: EventSpec) -> Any: raise EventHandlerTypeError(msg) event = spec._to_event(ctx.router_data) name = event.name + 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) @@ -892,6 +936,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..f8c64ad0a30 --- /dev/null +++ b/packages/reflex-base/src/reflex_base/event/processor/browser_calls.py @@ -0,0 +1,239 @@ +"""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" + +# 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. + + 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. + """ + + _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]], + ) -> 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. + 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. + + Returns: + The value the browser sent back. + + Raises: + TimeoutError: If no result arrives within the timeout. + """ + rid = uuid.uuid4().hex + 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. + await emit( + token, + dataclasses.replace(event, payload={**event.payload, RID_KEY: 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. 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: + 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 was + never made) is dropped. + + Args: + rid: The request id of the call. + outcome: ``{"json": }``, or ``{"error": {"name", + "message", "stack", "kind"}}`` when the script failed. + """ + future = self._futures.get(rid) + if future 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: + # 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( + "", + "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. + + 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 (tab := self._tabs.get(token)) is None: + return + 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 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 connected client token. + page: The page load it connected from. + """ + 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 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, message: str) -> None: + """Fail a client's calls with BrowserDisconnectedError. + + Args: + token: The client token. + message: The error's message. + """ + 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 915c0e05bcd..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 @@ -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,38 @@ 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 (page := event_namespace._page_of(token)) is None: + msg = ( + 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, page, 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 +264,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 +401,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 +530,22 @@ 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, 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.connect(token, page) async def enqueue_many(self, token: str, *events: Event) -> Sequence[EventFuture]: """Enqueue multiple events to be processed. @@ -565,6 +618,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..183c595f012 100644 --- a/packages/reflex-base/src/reflex_base/utils/exceptions.py +++ b/packages/reflex-base/src/reflex_base/utils/exceptions.py @@ -322,6 +322,49 @@ 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``; empty + when the backend, not the browser, found the error. + message: Its message. + stack: Its stack trace, if the browser had one. + """ + # 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 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): + """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/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 7486b1dac04..5bc0cfafa14 100644 --- a/packages/reflex-frontend/src/utils/state.js +++ b/packages/reflex-frontend/src/utils/state.js @@ -30,6 +30,15 @@ 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"; + +// 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 @@ -161,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. * @@ -591,6 +604,127 @@ 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 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, 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, + addEvents, + socket, + navigate, + params, + ); + } + const fn = + typeof event.payload.function === "string" + ? runScript(event.payload.function, addEvents, socket, navigate, params) + : event.payload.function; + 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. + * + * 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) => { + 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. + * + * ``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 plain data (objects, arrays, strings, numbers, booleans or null) instead.`, + ); + } + 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 +936,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.payload.rid) { + // The backend awaits the result: an error is its to handle. + void sendScriptResult(socket, event.payload.rid, () => + runEventScript(event, socket, navigate, params), + ); + return; + } try { await applyResultCallback( event, - event.payload.function(), + runEventScript(event, 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); } @@ -1121,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/run_script.test.js b/packages/reflex-frontend/tests/run_script.test.js index f561ee2f7ca..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; @@ -120,3 +128,188 @@ describe("_call_script", () => { expect(seen).toEqual([7]); }); }); + +describe("awaited script results", () => { + const awaited = (event) => { + const socket = { emit: vi.fn() }; + return { + socket, + 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)); + 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("describes a thrown value that cannot become a string", async () => { + // String() throws on an object without a prototype. + 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 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", + "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; 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) => { + 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.mock.calls).toEqual([ + ["boom", null, null, null, new Error("boom")], + ]); + expect(socket.emit).not.toHaveBeenCalled(); + }); +}); 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 3d9229c599c..8d6d484283e 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 @@ -1261,6 +1262,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, @@ -2682,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 @@ -2728,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. @@ -2761,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}") @@ -2778,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: @@ -2787,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 @@ -2845,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: @@ -2871,6 +2888,20 @@ def on_disconnect(self, sid: str) -> asyncio.Task | None: return task return None + 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: + 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 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 ) -> None: @@ -3110,9 +3141,22 @@ 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_KEY), str): + logger.debug(f"Ignoring malformed result payload from SID {sid}.") + return + 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: @@ -3122,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) @@ -3144,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/integration/tests_playwright/test_call_script.py b/tests/integration/tests_playwright/test_call_script.py index e9fa0d84444..8fc15ea4588 100644 --- a/tests/integration/tests_playwright/test_call_script.py +++ b/tests/integration/tests_playwright/test_call_script.py @@ -9,12 +9,21 @@ 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.""" from pathlib import Path import reflex as rx + from reflex.utils.exceptions import ( + BrowserDisconnectedError, + BrowserResultSerializationError, + BrowserScriptError, + ) inline_scripts = """ let inline_counter = 0 @@ -44,6 +53,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): + 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, 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 = [answer] @rx.event def call_script_callback(self, result): @@ -292,6 +339,33 @@ 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( + "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"), + 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", @@ -367,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 @@ -525,3 +601,130 @@ 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. 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() + 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'}") + + +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." + ) 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..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 @@ -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 @@ -5752,3 +5753,172 @@ 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. + """ + 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. + """ + 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 == [ + ( + "`_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 new file mode 100644 index 00000000000..c1b05479da5 --- /dev/null +++ b/tests/units/reflex_base/event/processor/test_browser_calls.py @@ -0,0 +1,391 @@ +"""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}) + +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.""" + + 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() + return self.sent[0][1].payload["rid"] + + +async def _start_call( + calls: BrowserCalls, timeout: float | None = None, token: str = "tok" +) -> tuple[Browser, asyncio.Task[Any], str]: + """Start a call to the tab of page ``p1`` 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, "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() + 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(rid, {"rid": rid, "json": '{"a": [1, null]}'}) + assert await task == {"a": [1, None]} + _assert_forgotten(calls) + + +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("unknown", {"json": "2"}) + await asyncio.sleep(0) + assert not task.done() + calls.resolve(rid, {"json": "3"}) + calls.resolve(rid, {"json": "4"}) + assert await task == 3 + _assert_forgotten(calls) + + +@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(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 + + +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"), + [ + ( + {}, + _unreadable( + "the JSON object must be str, bytes or bytearray, not NoneType" + ), + ), + ( + {"json": "{"}, + _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}, + ( + "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_result_the_backend_cannot_read_raises_a_serialization_error( + outcome: dict[str, Any], expected: str +): + """A result the backend cannot parse fails the call instead of hanging it. + + Args: + outcome: The outcome the browser sent. + expected: The error's message. + """ + calls = BrowserCalls() + _, task, rid = await _start_call(calls) + calls.resolve(rid, outcome) + with pytest.raises(BrowserResultSerializationError) as exc_info: + await task + 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", "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. 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_forgotten(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() + _, 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) + 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(): + """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._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_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) + 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(rid, {"json": "true"}) + assert await task is True + _assert_forgotten(calls) + + +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) + 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_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.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_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, and their timers.""" + calls = BrowserCalls() + _, away, _ = await _start_call(calls) + calls.disconnect("tok", 5) + timer = calls._tabs["tok"].grace_timer + _, connected, _ = await _start_call(calls, token="other") + calls.close() + for task in (away, connected): + with pytest.raises(asyncio.CancelledError): + await task + assert timer is not None + assert timer.cancelled() + _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 7302bbeb6d2..86309af949d 100644 --- a/tests/units/reflex_base/event/processor/test_event_processor.py +++ b/tests/units/reflex_base/event/processor/test_event_processor.py @@ -27,9 +27,14 @@ ) 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 +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]] = [] @@ -2164,3 +2169,111 @@ 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, **pages: str): + """Connect the given tokens. + + Args: + pages: The page load each connected client token connected from. + """ + self.pages = pages + self.updates: list[tuple[str, Any]] = [] + self.sent = asyncio.Event() + + def _page_of(self, token: str) -> str | None: + """Get the page load of a connected client. + + Args: + token: The client token. + + Returns: + The page id, or None when the token is not connected. + """ + return self.pages.get(token) + + 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() + return self.updates[-1][1].events[0].payload["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 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="p1") + 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) == ( + "`_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)) + rid = await namespace.next_rid() + assert [(token, update.events) for token, update in namespace.updates] == [ + ("tok", [dataclasses.replace(event, payload={**event.payload, "rid": rid})]) + ] + processor._on_disconnect("tok") + processor._on_connect("tok", "p1") + await asyncio.sleep(0.02) + 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) 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() + 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..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 @@ -98,3 +101,30 @@ 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_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), + ], + ) + 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) 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 diff --git a/tests/units/test_app.py b/tests/units/test_app.py index b348f5f4eac..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 @@ -5651,6 +5651,153 @@ 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 + + +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_a_call_by_its_request_id( + event_namespace_with_processor_mock: EventNamespace, +): + """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 + resolve = cast(Mock, namespace.app.event_processor._browser_calls.resolve) + outcome = {"rid": "r1", "json": "1"} + # 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("sid1") + await namespace.on_result("sid1", ["r1"]) + await namespace.on_result("sid1", {"rid": 1, "json": "1"}) + resolve.assert_not_called() + + +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 live on 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") + 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 + + +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: + 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() + 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 async def test_link_token_to_sid_records_the_connecting_identity( token: str, 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