perf: elide unchanged connection-scoped router fields from deltas

[Alek99]

What

Every client-side navigation fires on_load_internal, which reassigns state.router and marks the whole var dirty — so every navigation delta re-ships the complete RouterData, including the session block and every request header (twice, via raw_headers). Measured on a minimal app with no cookies:

• navigation delta: 1,870 bytes, of which 1,323 bytes (71%) are session + headers that cannot change for the life of the websocket
• apps with real auth cookies re-ship those on every page change too

This lands on the client on every nav (and every event that carries a changed router_data), gets JSON-parsed, and replaces the router value in the root state context.

How

Ship session/headers only when they actually changed:

• BaseStateEventProcessor compares the previous router when reassigning; if session and headers are unchanged it arms a transient _router_static_unchanged flag on the root state (never pickled meaningfully — recomputed on every reassignment).
• get_delta then serializes only the per-navigation fields (page, url, route_id) for the router var via serialize_partial_router_data (extracted from the existing serializer, so the two can't drift).
• applyDelta on the frontend merges partial router payloads over the previously received value, so session/headers carry forward on the client.
• Fail-safe: any direct router write clears the flag in __setattr__ — covering the connect handler's sid update and the linked-token client_token rewrite — falling back to the full payload.

Reconnects and cross-worker moves are safe by construction: a new socket has a new session_id, so the comparison fails and the full router is sent; a state restored on another worker has empty router_data (excluded from pickle), which also fails the comparison.

Compatibility

Rolling deployments / cached frontends. A pre-upgrade frontend replaces the router value instead of merging, so it must never receive a partial payload. The frontend already advertises the exact version it was compiled by as the websocket subprotocol, and the backend already compares it; this PR turns that existing handshake into the capability gate. on_connect records subprotocol == backend version on the root state (_partial_router_capable), and get_delta sends the partial payload only when it is set. Older bundles, proxies that strip the subprotocol, and polling transports all fall back to the full router in every delta. The capability survives pickling and worker moves, and reconnects re-evaluate it — a tab that reconnects with a stale cached bundle after a redeploy is downgraded to full payloads. Verified live by forcing a mismatched subprotocol from a real browser client: every navigation delta carried the full session/headers.

Internal fields are reserved. _router_static_unchanged (transient, never pickled) and _partial_router_capable are declared is_var=False fields on BaseState, added to RESERVED_BACKEND_VAR_NAMES, and __init_subclass__ raises ReservedStateFieldError if a user state declares either name — a collision surfaces as an error instead of silently steering delta serialization.

Measured result

• Navigation delta drops 1,870 → 516 bytes (−72%) on the minimal app.
• Rendered router vars (State.router.session.client_token, State.router.headers.user_agent) verified intact on the client after slim deltas, across navigations and events, on a fresh boot.
• New unit test test_partial_router_delta covers full-on-first-send, partial-when-unchanged, and full-again-after-direct-write. test_dynamic_route_var_route_change_completed_on_load updated: its router_data carries no sid/headers, so the partial payload correctly applies from the first on_load. Full unit suite: 7,460 passed.

[chatgpt-codex-connector]

You have reached your Codex usage limits for code reviews. You can see your limits in the Codex usage dashboard.

[codspeed-hq]

Merging this PR will not alter performance

✅ 27 untouched benchmarks
⏩ 8 skipped benchmarks¹

---

_{Comparing alek/router-delta-slim (7f506e8) with main (d28be54)}

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. ↩

[greptile-apps]

Greptile Summary

The PR reduces navigation delta sizes by omitting unchanged connection-scoped router data while preserving compatibility with clients that cannot merge partial payloads.

• Compares session and header data before selecting partial serialization.
• Merges partial router updates into existing frontend state.
• Gates partial payloads on the websocket version handshake and reserves internal bookkeeping fields.
• Adds coverage for capability gating, changed connection data, direct writes, and reserved-field collisions.

Confidence Score: 5/5

The PR appears safe to merge.

No blocking failure remains.

Important Files Changed

Filename	Overview
packages/reflex-base/src/reflex_base/.templates/web/utils/state.js	Merges partial router payloads over the router data already held by the frontend.
packages/reflex-base/src/reflex_base/event/processor/base_state_processor.py	Detects whether connection-scoped router fields remained unchanged during event processing.
reflex/app.py	Records partial-router capability from the websocket subprotocol version handshake.
reflex/istate/data.py	Separates full RouterData serialization from its per-navigation partial representation.
reflex/state.py	Tracks capability and invalidation state and conditionally emits partial router deltas.
tests/units/test_app.py	Exercises event-processor behavior for legacy clients and changed session or header data.
tests/units/test_state.py	Covers partial serialization gates, direct-write invalidation, and reserved internal fields.

_{Reviews (9): Last reviewed commit: "clarify that the headers-fallback leg re..." | Re-trigger Greptile}

[cubic-dev-ai]

All reported issues were addressed

<sub>Reply with feedback, questions, or to request a fix.

Re-trigger cubic</sub>

[chatgpt-codex-connector]

You have reached your Codex usage limits for code reviews. You can see your limits in the Codex usage dashboard.

[cubic-dev-ai]

All reported issues were addressed across 11 files

<sub>Reply with feedback, questions, or to request a fix.

Re-trigger cubic</sub>

[cubic-dev-ai]

All reported issues were addressed across 3 files (changes from recent commits).

<sub>Tip: Review your code locally with the cubic CLI to iterate faster.

Re-trigger cubic</sub>

[Alek99]

On the CodSpeed regression (test_var_access[non_mutable_scalar], −4.72%)

Investigated rather than acknowledged blindly; summary:

• The diff contains no read-path change. state.scalar reads go through BaseState.__getattribute__, which this PR does not touch — the only __setattr__ addition is on the write path, and get_delta is not in the benchmark loop.
• Walltime cannot reproduce it. Interleaved A/B of the benchmark's exact loop (10k scalar reads, 200 samples/round, 4 alternating rounds, PR head vs 7e57be74) shows the PR equal-or-faster in every round — e.g. per-round minimums 2.86–2.98 ms (PR) vs 2.94–3.09 ms (base).
• Most plausible mechanism for the instruction-count delta: the two new declared fields (_router_static_unchanged, _partial_router_capable) add two entries to every state instance's __dict__, which can shift dict sizing/probing, and added code in state.py shifts layout — the kind of effect simulation mode registers but wall clock does not. The same cost profile applies to any new BaseState field (e.g. _was_touched).

The fields are the review-required design (declared + reserved so user states cannot silently shadow them), so I'd rather not contort the storage to appease a micro-benchmark that walltime can't confirm. Suggest acknowledging on CodSpeed; happy to investigate further if the report shows the extra instructions somewhere other than dict handling.

[masenf]

i think a better approach here would be to break the router data up into separate base vars so we're not working against reflex's delta system.

each type of router data is already defined independently, so we could keep the top level RouterData object as a switchboard that gives you the per-field base var value instead of RouterData being the root of a dataclass that gets entirely serialized.

i'm not a fan of the special case here

[Alek99]

The integration-app-harness (memory, 3.14, 1) failure is the known pre-existing react-helmet race (test_call_script → "scripts not loaded"), root-caused and fixed in #6905 (analysis): react-helmet's rAF-deferred head flush is intermittently lost around hydration, dropping rx.script tags — ~1-in-5 locally on main's code path, independent of this PR. This branch doesn't carry the fix to avoid cross-PR conflicts; once #6905 merges, a rebase inherits it and this shard stops flaking. Rerun triggered.