feat: warn about JavaScript invocations that are never delivered to the client

[totally-not-ai]

JavaScript invocations scheduled from the server are retained in memory until they are written into a response for the client, so an application that keeps scheduling invocations that are never delivered runs out of memory. Nothing reports this today: the developer sees it for the first time as hundreds of thousands of PendingJavaScriptInvocation and StateTree$BeforeClientResponseEntry instances in a heap dump, with no indication of which component schedules them or why they are stuck. See this forum thread for how hard this is to diagnose from the outside, and #17286 for the related case of invocations retained for invisible components.

Invocations pile up in three different places, which is why counting only the queue in UIInternals would not have covered the reported case:

• Element.executeJs parks the invocation in a beforeClientResponse entry on its state node, and those entries are only flushed while a UIDL response is being written. Without a response, the invocations never even reach UIInternals.
• An executeJs call on a detached node registers an attach listener that holds the invocation until the node is attached again.
• UIInternals.pendingJsInvocations grows through Page.executeJs, and invocations owned by an invisible component are deliberately re-queued on every purge.

What changed

• Counting at the source. The invocations that have been scheduled for a UI without being sent are counted in UIInternals, hooked into the PendingJavaScriptInvocation lifecycle: the constructor counts one, and setSentToBrowser() / cancelExecution() uncount it. Counting happens when an invocation is scheduled rather than when it enters the UI queue, so it covers all three cases above, including the invocations that never reach that queue. Each invocation remembers which UI counted it, so the same counter is decremented later even if its owner has been detached meanwhile. The counter is deliberately not kept per state node: a running application has far more nodes than UIs, so even one field per node multiplies into a significant amount of resident memory for nodes that never schedule any JavaScript.

• A warning that identifies the culprit. PendingJavaScriptInvocationUtil logs a warning when a UI reaches 1000 undelivered invocations, and repeats it only when the count grows tenfold, so a leaking application logs a handful of lines instead of thousands. The message names the component the most recently scheduled invocation belongs to (plus its creation location when component tracking is enabled), its expression, and whether that owner is detached, invisible, or in a UI with no open push connection. Debug logging adds the executeJs call site. Example, from a UI with push disabled that keeps updating a field:

  1000 JavaScript invocations scheduled for com.example.MyField (state node 3) have not been sent to the browser yet. The most recent expression is: 'return (async function() { this.value = $0}).apply($1)'. There is no open push connection for the UI (push mode DISABLED), so nothing can be delivered until the browser sends a request. A closed browser tab whose session has not expired yet, or a push connection that was never established, look exactly like this. […]

• Advice for the common cause. The message explains what to do when only the latest value is relevant for the client, for example a progress value or the current time: keep the PendingJavaScriptResult and cancel it before scheduling the next update (which is what Flow itself does for the page title), or set an element property instead, since only the last value of a property is sent.

• UI.getLastUpdateSentTimestamp() exposes when the pending updates of a UI were last purged into a response for the client, stamped in UIInternals.dumpPendingJavaScriptInvocations(). A background task that updates a UI at an interval can compare it against the current time and stop scheduling updates while nothing is reaching the client — which works for polling as well as for push, and does not require the application to hold the PendingJavaScriptResult of updates it never scheduled itself (a Binder reading a bean, for instance). It is initialized when the UI is created, so a UI that has never sent anything reports its creation time rather than 0. The javadoc is explicit that this says the updates were written towards the client, not that the client received them; the warning message points to the method as well.

• Configuration. The new pendingJavaScriptInvocationsWarningThreshold init parameter changes the threshold, and 0 disables the warning. Counts are only inspected at every 100th invocation to keep the scheduling path to a single modulo, so a configured threshold is in practice rounded up to a multiple of 100.

API

Added: UI.getLastUpdateSentTimestamp(), UIInternals.getLastUpdateSentTimestamp() and InitParameters.PENDING_JAVASCRIPT_INVOCATIONS_WARNING_THRESHOLD. Nothing removed or changed. PendingJavaScriptInvocationUtil and the counter accessors on UIInternals are package private, and StateNode is untouched. The added memory is one int per UI, plus one reference on each PendingJavaScriptInvocation that is waiting to be sent.

Verification

mvn -pl flow-server test passes (5056 tests, 12 of them new). The new tests cover the warning tiers (first warning at the threshold, then only tenfold, and 0 disabling it), the counter over the scheduled → sent and scheduled → canceled paths including a double cancel, an invocation for a detached owner being counted in the current UI and one with no UI at all not being counted, the contents of the message for a detached, an invisible and a connection-less owner, truncation of long expressions to a single line, executeJs on a detached element, and the purge timestamp being updated by a purge but not by scheduling an invocation. The end-to-end behaviour was checked separately by scheduling 1000 executeJs calls in a UI without push and confirming that exactly one warning is logged, with the text quoted above.

[github-actions]

Test Results

 1 373 files  + 1   1 374 suites  +1   1h 29m 15s ⏱️ + 2m 14s
10 462 tests +17  10 395 ✅ +17  67 💤 ±0  0 ❌ ±0 
10 781 runs  +17  10 713 ✅ +17  68 💤 ±0  0 ❌ ±0 

Results for commit e0289cf. ± Comparison against base commit 1f26a22.

♻️ This comment has been updated with latest results.

[sonarqubecloud]

Quality Gate failed

Failed conditions
72.4% Coverage on New Code (required ≥ 80%)

See analysis details on SonarQube Cloud