perf: cut socket-layer per-event overhead (header cache, route LRU, deferred event routing)

[Alek99]

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

• Bug fix (non-breaking change which fixes an issue)

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?

Note: the orjson wire-encoding change was dropped from this PR per @masenf's request, to be taken through @benedikt-bartscher's more complete PR. This PR now covers only the header cache, route LRU, and lock-hold changes.

Three per-event costs on the websocket hot path (ENG-10098):

1. Per-sid header cache (reflex/app.py) — on_event re-decoded every ASGI header from bytes and re-parsed x-forwarded-for on every event, though headers are fixed for a connection's lifetime. Now decoded once per sid, evicted on disconnect. A fresh dict is handed out per event so router_data mutations can't leak into the cache.

2. Route resolution LRU (reflex/route.py) — the router ran a linear regex scan over all routes per event for a path that rarely changes. The per-router get_route closure is now lru_cache(maxsize=1024); the route set is fixed for a router's lifetime (it was already baked in at closure creation), so no staleness is introduced.

3. Deferred chained-event routing (base_state_processor.py) — the final chained-event routing (frontend event encode+emit, backend event enqueue) ran while holding the state lock; it now runs after release. Deltas intentionally still emit under the lock: delta values reference live state containers (get_value unwraps proxies without copying), and e.g. emit_lost_and_found awaits redis before pickling, so a post-release emit could serialize data mutated by the next lock holder (thanks @masenf / the Codex review for flagging this — the delta-emit deferral from an earlier iteration was reverted). Chained-event payloads are proxy-detached at creation, so their deferred routing is safe. Per-token ordering is unchanged (the next event for a token dispatches only after the current task finishes, deferred routing included).

Measured results (Python 3.13, real before/after code with stubbed config):

cost	before	after	speedup
header decode per event (16 headers)	2.96 µs	0.24 µs	12.5x
route match per 4 paths (69-route app)	29.7 µs	0.32 µs	93x

Existing processor/route/app unit tests plus the integration suites cover the behavior.

Linear: ENG-10098

🤖 Generated with Claude Code

https://claude.ai/code/session_01Sns7EuBPYvfGCxRSRZ1bUx

[greptile-apps]

Greptile Summary

This PR reduces websocket event overhead in the socket and routing paths. The main changes are:

• Per-connection header and client-IP caching for socket events.
• Cached route resolution for repeated paths.
• Deferred final chained-event routing after the state lock is released.
• Performance news entries for the changed event paths.

Confidence Score: 5/5

This looks safe to merge.

• No blocking issues found in the changed code.

Important Files Changed

Filename	Overview
packages/reflex-base/src/reflex_base/event/processor/base_state_processor.py	Defers final chained-event routing while keeping delta emission inside the state lock.
reflex/app.py	Caches decoded websocket headers and client IP data per socket id, with cleanup on disconnect.
reflex/route.py	Adds an LRU cache to the per-router route lookup closure.
news/6744.performance.md	Adds a performance news entry for websocket overhead reductions.
packages/reflex-base/news/6744.performance.md	Adds a performance news entry for deferred chained-event routing.

_{Reviews (4): Last reviewed commit: "refactor: drop orjson wire encoder from ..." | Re-trigger Greptile}

[codspeed-hq]

Merging this PR will not alter performance

✅ 26 untouched benchmarks
⏩ 8 skipped benchmarks¹

---

_{Comparing claude/reflex-perf-optimizations-21kg8y-socket (0c8d27e) with main (48f229f)}

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

[linear-code]

ENG-10098

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: bbf451db35

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[chatgpt-codex-connector]

Snapshot deltas before releasing the state lock

When a foreground handler changes a mutable state var while a background task is waiting on the same state lock, this releases the lock before the deferred ctx.emit_delta serializes the delta. BaseState.get_delta() builds the delta with self.get_value(prop), so list/dict values are still the original mutable objects; a background task can acquire the lock and mutate those objects before this deferred emit runs, causing the client to receive the background mutation in the foreground update or out of order. Please either emit/encode while the lock is held or copy/freeze the resolved delta before releasing it.

Useful? React with 👍 / 👎.

[Alek99]

Confirmed and fixed in ac961f3 — get_value does return the live containers, and emit_lost_and_found awaits redis before pickling, so the window was real on multi-instance deployments. Deltas now emit inline under the lock again (exactly as before this PR); only the routing of final chained events is deferred past the lock, which is safe because event payloads are detached from state at creation time.

---

Generated by Claude Code

[benedikt-bartscher]

related to my orjson pr #6116

[masenf]

can we decouple the orjson changes from this patch, i'd rather take those through @benedikt-bartscher more complete PR

[Alek99]

Done — dropped the orjson wire encoder (and its parity tests, benchmark, and dependency edge) in 0c8d27e, so it can go through @benedikt-bartscher's PR instead. This PR now scopes to just the per-connection header cache, route LRU, and deferring chained-event routing past the state lock (delta emit stays under the lock, as discussed above).

---

Generated by Claude Code