Repository navigation
Await the results of browser scripts from background handlers - #7955
FarhanAliRaza wants to merge 22 commits into
Conversation
A background event handler can now `await rx.call_script(...)`,
`rx.call_function(...)` or `rx.run_script(...)` and get the script's
result back, instead of passing a callback that the browser evals.
- Event gains an optional `rid`, sent only when the backend awaits the
event, so ordinary events serialize as before. Clients cannot set it.
- The browser runs the script and answers on a new `result` socket event
with `{rid, json}` or `{rid, error}`. It does not await the script in
the event queue, so a script waiting on the user holds up nothing.
- BrowserCalls keeps the pending calls per token. A result settles a
call only for the token it was sent to. A disconnect starts a grace
period (browser_call_grace_period); a reconnect within it keeps the
calls, since socket.io buffers the result emit.
- Awaiting under the state lock (a foreground handler, `async with
self`) raises EventHandlerTypeError, as does passing a callback too.
- Timeouts default to browser_call_timeout, overridable with timeout=.
- Errors raise BrowserScriptError, BrowserResultSerializationError,
BrowserDisconnectedError or TimeoutError.
Claude-Session: https://claude.ai/code/session_01LwJUCVxPh3ihrnaFn6CWnf
add_args binds extra arguments to the event's signature parameters, so the new keyword-only timeout absorbed one. The signature the event reports now leaves it out. runEventScript declares the late-bound addEvents alias itself, as every function that runs user code must. Claude-Session: https://claude.ai/code/session_01LwJUCVxPh3ihrnaFn6CWnf
[Medium impact] The PR appears safe to merge; no new actionable issues were found. SummaryAdds awaited browser-script results for background handlers, with timeouts, reconnect grace periods, and clear errors.
Reviews (10) · Last reviewed commit: "Start every waiting awaited script throu..." · Reviewed by Greptile |
String() throws on an object without a prototype, so a script rejecting with one sent no result and its call waited for the timeout. Error fields now fall back to Object.prototype.toString. The new tests also import the exceptions at the top of their modules. Claude-Session: https://claude.ai/code/session_01LwJUCVxPh3ihrnaFn6CWnf
Merging this PR will regress 1 benchmark3 warnings
Warning Please fix the performance issues or acknowledge them on CodSpeed. Performance Changes
Tip Investigate this regression by commenting Comparing Footnotes
|
The rid field on Event cost every Event one more frozen field write (CodSpeed: -7% on from_event_type). Only _call_script and _call_function ever carry a request id, so it now goes in their payload and no other event pays for it; the Event serializer and the _EVENT_FIELDS change are gone with the field. The script event signature is also computed once instead of on every call, which made console_log 8% slower. Claude-Session: https://claude.ai/code/session_01LwJUCVxPh3ihrnaFn6CWnf
|
CodSpeed on 53e4424 reports
The two regressions earlier runs found ( Generated by Claude Code |
Pass name, message and stack to Exception.__init__ so the error survives pickling, and format it in __str__; an error the backend found itself has no JavaScript name and prints its message alone. Claude-Session: https://claude.ai/code/session_01LwJUCVxPh3ihrnaFn6CWnf
A call's own timeout=None already waits without a limit; the config setting can now say the same. Claude-Session: https://claude.ai/code/session_01LwJUCVxPh3ihrnaFn6CWnf
The timeout only matters to the backend task that awaits the call, so it is kept on the spec (_BrowserCallSpec) instead of in the event args: a trigger or a yielded script no longer sends an unused timeout to the browser. Claude-Session: https://claude.ai/code/session_01LwJUCVxPh3ihrnaFn6CWnf
A thrown value whose name or message getter throws, or a revoked Proxy, made describeScriptError throw, so the backend never got a reply and waited for its timeout. It now gets a generic error instead. The error for a function or symbol result also says what to return instead. Claude-Session: https://claude.ai/code/session_01LwJUCVxPh3ihrnaFn6CWnf
A reloaded page reconnected under its sessionStorage token within the grace period, which kept calls whose script had died with the old page: they waited for their timeout, forever with timeout=None. The frontend now sends a random page id with every connect; a connect from another page load under the token fails the token's pending calls at once, while a reconnect of the same page keeps them. A call made between a socket's disconnect and the cleanup of its token passed the connected check and registered without a grace timer. The namespace now drops the page of a socket in on_disconnect itself, and a token whose socket has no page is not connected. Results settle their call by request id alone, so a tab that was given a new token on reconnect still delivers them. A result Python cannot parse (nested too deeply, or malformed) always fails its call instead of leaving it pending. The error messages say what happened, why, and what to change. Claude-Session: https://claude.ai/code/session_01LwJUCVxPh3ihrnaFn6CWnf
The CallScript app drops its socket and reconnects within the grace period (the result still arrives), past it (BrowserDisconnectedError), and reloads the page (BrowserDisconnectedError at once). A vitest covers a script dispatching events through the late-bound addEvents. Claude-Session: https://claude.ai/code/session_01LwJUCVxPh3ihrnaFn6CWnf
The Awaiting Results section now lists the rules, then each error with its exact message and fix, and says a reload fails the call at once. The configuration page shows the settings in rxconfig.py and that browser_call_timeout may be None. Claude-Session: https://claude.ai/code/session_01LwJUCVxPh3ihrnaFn6CWnf
with_args rebuilt the spec from four named fields, so a copy of an awaited call lost its timeout. It now copies every field. Claude-Session: https://claude.ai/code/session_01LwJUCVxPh3ihrnaFn6CWnf
Each loaded app sends its own page id, so the size-check test now replaces it with a placeholder before comparing frames; the id has a fixed length, so the measured sizes are unchanged. Claude-Session: https://claude.ai/code/session_01LwJUCVxPh3ihrnaFn6CWnf
EventSpec.with_args used dataclasses.replace, which passes fn to CallableEventSpec's constructor along with the fields it already derives from fn, so copying clear_selected_files raised TypeError. EventSpec keeps its explicit constructor call; _BrowserCallSpec overrides with_args to keep its timeout. Claude-Session: https://claude.ai/code/session_01LwJUCVxPh3ihrnaFn6CWnf
A 100,000-deep payload exhausts the JSON parser on some interpreters and not on others (CI's Python 3.14 and 3.15 parse it), so the test now makes the parser raise RecursionError the way it does at that depth. Claude-Session: https://claude.ai/code/session_01LwJUCVxPh3ihrnaFn6CWnf
String() already throws on an object without a prototype, so the outer fallback describes it as it does a throwing getter or a revoked Proxy; the separate toText fallback and the kind parameter go. Claude-Session: https://claude.ai/code/session_01LwJUCVxPh3ihrnaFn6CWnf
EventContext.call_frontend only checked for a missing frontend before calling call_frontend_impl, for its single caller _await_browser_call, which now does both. EventProcessor._on_connect only forwarded to BrowserCalls.connect; the socket's connect handler calls that directly, as its result handler already calls BrowserCalls.resolve. The processor and app tests no longer repeat the reconnect and reload sequences test_browser_calls pins, nor the not-connected check test_page_of_only_for_a_live_socket_on_this_instance pins. Claude-Session: https://claude.ai/code/session_01LwJUCVxPh3ihrnaFn6CWnf
A call cancels its tab's grace timer as it ends, so close() only cancels the futures. Merge the two zero-grace-period tests into one. Claude-Session: https://claude.ai/code/session_01LwJUCVxPh3ihrnaFn6CWnf
The hooked and Var scripts exercise call_script's existing branches, not the timeout; and CallableEventSpec.with_args is unchanged by this branch. Claude-Session: https://claude.ai/code/session_01LwJUCVxPh3ihrnaFn6CWnf
|
CodSpeed: I counted calls into everything this PR adds ( The benchmark makes no calls into the added code. Under coverage, the only added lines it executes are class, field and function definitions run at import time, plus the setup before the measured body. CodSpeed's own warnings say this benchmark "ran on different hardware" and "in a different software environment" than its baseline. It is also flagged by the same amount on #7961, which changes unrelated code (event-trigger argument binding). So this looks like runner variance; there's no code to fix here. Generated by Claude Code |
All Submissions:
Type of change
Description
Part of ENG-9127.
Problem. Getting a value out of the browser today means passing a
callback. The browser evals that callback string, and the code that asks for the value ends up split from the code that uses it.Change. A background handler can now
awaitthe script itself:This works for
rx.call_script,rx.call_functionandrx.run_script. If the script returns a promise, the handler gets the value the promise resolves to.Rules.
async with self. Under the lock, every other event of the tab would wait for the browser, so that raisesEventHandlerTypeError. So does passingcallback=and awaiting.browser_call_timeout(30 s by default;Nonemeans no limit), ortimeout=on a single call. The timeout stays on the backend and is never sent to the browser.browser_call_grace_period(5 s) still delivers its result.Errors. Each message states the problem, its cause and the fix, and a test compares the full text:
BrowserScriptErrorname,messageandstack, and is picklable.BrowserResultSerializationErrorwindow, a function, a value nested too deep, or a frontend from another Reflex version.TimeoutErrorBrowserDisconnectedError(aConnectionError)Design.
rid, a uuid4) in the event payload. The browser runs the script and replies on a newresultsocket event with{rid, json}or{rid, error}. It sends that reply without blocking its event queue, so a script that waits on the user holds up no other event.BrowserCallssettles a call by itsridalone. The id is unguessable, so a tab that reconnects under a new token still delivers its result. A per-token index exists only for disconnects and grace timers.RecursionError.Out of scope.
_call_js, a separate stacked PR).New Feature Submission:
Changes To Core Features:
Tests:
test_call_script.py: values, errors, timeouts, the lock rules, a socket drop inside and past the grace period, and a page reload. The grace period is set to 2 s for the test.Docs: "Awaiting Results" in
docs/api-reference/browser_javascript.md, with each rule and every error's exact message and fix. Both settings are indocs/advanced_onboarding/configuration.md.https://claude.ai/code/session_01LwJUCVxPh3ihrnaFn6CWnf