Skip to content

Await the results of browser scripts from background handlers - #7955

Draft
FarhanAliRaza wants to merge 22 commits into
mainfrom
farhan/focused-darwin-dx76ek-await-results
Draft

FarhanAliRaza wants to merge 22 commits into
mainfrom
farhan/focused-darwin-dx76ek-await-results

Conversation

@FarhanAliRaza

@FarhanAliRaza FarhanAliRaza commented Nov 21, 2026 •

Copy link
Copy Markdown
Contributor

All Submissions:

  • Have you followed the guidelines stated in CONTRIBUTING.md file?
  • Have you checked to ensure there aren't any other open Pull Requests for the desired changed?

Type of change

  • New feature (non-breaking change which adds functionality)
  • This change requires a documentation update

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 await the script itself:

@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']}"

This works for rx.call_script, rx.call_function and rx.run_script. If the script returns a promise, the handler gets the value the promise resolves to.

Rules.

  • Await outside the state lock: in a background handler, outside async with self. Under the lock, every other event of the tab would wait for the browser, so that raises EventHandlerTypeError. So does passing callback= and awaiting.
  • Timeout: browser_call_timeout (30 s by default; None means no limit), or timeout= on a single call. The timeout stays on the backend and is never sent to the browser.
  • Disconnects:
    • A tab that reconnects within browser_call_grace_period (5 s) still delivers its result.
    • A tab that reloads or navigates away fails the call as soon as the new page connects. It doesn't wait out the timeout.
    • A tab that doesn't come back fails the call when the grace period ends.

Errors. Each message states the problem, its cause and the fix, and a test compares the full text:

Exception Raised when
BrowserScriptError The script throws or its promise rejects. Carries the JS name, message and stack, and is picklable.
BrowserResultSerializationError The result cannot be sent as JSON: a DOM node, window, a function, a value nested too deep, or a frontend from another Reflex version.
TimeoutError No result arrived in time. The message names both ways to raise the limit.
BrowserDisconnectedError (a ConnectionError) The tab isn't connected to this worker, was reloaded, never came back, or the app runs without a frontend.

Design.

  • The backend puts a request id (rid, a uuid4) in the event payload. The browser runs the script and replies on a new result socket 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.
  • BrowserCalls settles a call by its rid alone. 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.
  • Each page load sends a random page id with every connect. When the same token connects with a new page id, the old page is gone, so its calls fail at once.
  • A reply is always sent, even when the thrown value can't be read (getters that throw, revoked proxies). The backend side catches every parse failure, including RecursionError.

Out of scope.

  • Routing a call to a tab connected to another worker. It fails immediately with an explicit message; use sticky sessions.
  • Awaiting JS module functions (_call_js, a separate stacked PR).

New Feature Submission:

  • Does your submission pass the tests?
  • Have you linted your code locally prior to submission?

Changes To Core Features:

  • Have you added an explanation of what your changes do and why you'd like us to include them?
  • Have you written new tests for your core changes, as applicable?
  • Have you successfully ran tests with your changes locally?

Tests:

  • Unit: the registry (resolve, timeout, grace period, reload, new token, cancellation, deep nesting), the processor wiring, the real app socket handlers with a real processor, and the config.
  • vitest: serialization, every thrown-value case, and ordering.
  • Playwright 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.
  • Coverage: 100% of the added Python lines and branches, and of the JS statements and branches.

Docs: "Awaiting Results" in docs/api-reference/browser_javascript.md, with each rule and every error's exact message and fix. Both settings are in docs/advanced_onboarding/configuration.md.

https://claude.ai/code/session_01LwJUCVxPh3ihrnaFn6CWnf

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
@linear-code

linear-code Bot commented Nov 21, 2026

Copy link
Copy Markdown

ENG-9127

@greptile-apps

greptile-apps Bot commented Nov 21, 2026 •

Copy link
Copy Markdown
Contributor

RetriggerView in GreptileConfidence Score: 5/5

[Medium impact] The PR appears safe to merge; no new actionable issues were found.

Summary

Adds awaited browser-script results for background handlers, with timeouts, reconnect grace periods, and clear errors.

  • Background handlers can await values from browser scripts.
  • Browser replies stay tied to the page that started each call.

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
@codspeed

codspeed Bot commented Nov 21, 2026 •

Copy link
Copy Markdown

Merging this PR will regress 1 benchmark

3 warnings

⚠️ 19 benchmarks are dominated by system calls

System calls cannot be simulated consistently and are left out of the measure. The reported value understates the real cost. Switch to the Walltime instrument to measure them.

Learn more about system calls

See affected benchmarks

⚠️ 2 benchmarks with a significant change ran on different hardware

Their base and head results were measured on machines with a different CPU, core count or memory, so the changes might not come from the code. Run base and head on the same runner type.

Learn more about Macro Runners

See affected benchmarks

⚠️ 2 benchmarks with a significant change ran in a different software environment

Their base and head results were measured with a different OS or toolchain, such as compiler, runtime or library versions, so the changes might come from this difference rather than from the code. Open an affected benchmark to see what changed.

See affected benchmarks

⚡ 1 improved benchmark
❌ 1 regressed benchmark
✅ 144 untouched benchmarks
⏩ 8 skipped benchmarks1

Warning

Please fix the performance issues or acknowledge them on CodSpeed.

Performance Changes

Benchmark BASE HEAD Efficiency
❌ test_state_access[write_own] 122.2 ms 129.6 ms -5.74%
⚡ test_console_log 658.1 µs 545.7 µs +20.6%

Tip

Investigate this regression by commenting @codspeedbot fix this regression on this PR, or directly use the CodSpeed MCP with your agent.


Comparing farhan/focused-darwin-dx76ek-await-results (f9e1af5) with main (df7f157)

Open in CodSpeed

Footnotes

  1. 8 benchmarks were skipped, so the baseline results were used instead. If they were deleted from the codebase, click here and archive them to remove them from the performance reports. ↩

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

Copy link
Copy Markdown
Contributor Author

CodSpeed on 53e4424 reports test_proxy_list_mutation at -4.81%. This is not caused by this PR:

  • 53e4424 differs from b33c046 only in tests/integration/tests_playwright/test_call_script.py, which no benchmark runs. On b33c046, CodSpeed listed test_proxy_list_mutation as untouched.
  • The PR does not change the state proxy or anything under reflex/istate.

The two regressions earlier runs found (test_console_log, test_from_event_type[event_spec]) were real; b33c046 fixed them. test_console_log is now 26% faster than main.


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

Copy link
Copy Markdown
Contributor Author

CodSpeed: test_state_access[write_own] doesn't run this PR's code.

I counted calls into everything this PR adds (call_script, call_function, run_script, _browser_call_spec, _script_signature, with_args, _await_browser_call, and the BrowserCalls methods) with a sys.setprofile hook that is active only while the benchmark body runs:

test_state_access[write_own]                       {}
# controls:
test_script_events_keep_their_timeout_off_the_wire {'call_script': 2, '_browser_call_spec': 4, '_script_signature': 1, 'call_function': 2, 'run_script': 1}
test_copies_of_a_script_event_keep_its_timeout     {'call_script': 1, '_browser_call_spec': 1, 'with_args': 2}

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

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant