fix(router-core): don't drop onRenderFinished listeners after stream fast path is reserved

[radosek]

Fixes #7529

Problem

reserveStreamFastPath() (introduced in #7497) silently dropped any onRenderFinished listener registered after the fast path was reserved:

onRenderFinished: (listener) => {
  if (cleanupStarted || streamFastPathReserved) return // listener lost
  renderFinishedListeners.push(listener)
},

With @tanstack/react-router-ssr-query, the integration registers an onRenderFinished listener (in router.options.dehydrate) that closes the dehydration query stream. When the fast path was reserved before that listener landed, the listener never ran, the query stream was never closed, and serializationFinished never became true — so the SSR response hung until the ~60s serialization timeout. Browsers often paint early, but bots/curl eat the full delay.

• Broken: router-core@1.171.7–1.171.9 (@tanstack/react-router@1.170.x)
• Works: router-core@1.171.6 / @tanstack/react-router@1.169.0

Fix

Register the listener regardless of the fast path. The fast path stream still calls setRenderFinished() when the app stream ends (makeFastPathStream -> finishSsrRendering()), so the listener fires at the correct time rather than being discarded. This keeps the original render-finished timing instead of invoking late listeners out of band.

Test

Added a regression test in ssr-server-cleanup.test.ts that reserves the fast path, then registers an onRenderFinished listener and asserts it is not dropped (fires on setRenderFinished). Verified it fails on main and passes with the fix.

• router-core unit suite: 1179 passed / 3 expected-fail (pre-existing it.fails deepEqual docs)
• router-ssr-query-core: passing

Summary by CodeRabbit

• Bug Fixes

  • Fixed an SSR streaming issue where listeners registered after the stream fast-path reservation were previously ignored, which could cause server responses to hang; such listeners now run when the stream finishes so responses close reliably.

• Tests

  • Added a regression test to verify late-registered listeners are invoked and cleanup proceeds correctly in SSR streaming fast-path scenarios.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: 078d98ce-937a-40c7-8a44-ad05f6318ba6

📥 Commits

Reviewing files that changed from the base of the PR and between ad107d2 and ea60ebe.

📒 Files selected for processing (3)

• .changeset/cool-streams-close.md
• packages/router-core/src/ssr/ssr-server.ts
• packages/router-core/tests/ssr-server-cleanup.test.ts

🚧 Files skipped from review as they are similar to previous changes (2)

• packages/router-core/src/ssr/ssr-server.ts
• packages/router-core/tests/ssr-server-cleanup.test.ts

---

📝 Walkthrough

Walkthrough

Fixes an SSR streaming regression: onRenderFinished no longer drops listeners registered after the stream fast path is reserved; such listeners are retained and invoked (verified by a regression test and documented in a changeset).

Changes

SSR Listener Execution Fix

Layer / File(s)	Summary
onRenderFinished behavior change packages/router-core/src/ssr/ssr-server.ts	Stops early-returning when streamFastPathReserved is true; listeners registered after reservation are added so they run when setRenderFinished() executes.
Regression test for fast-path listener packages/router-core/tests/ssr-server-cleanup.test.ts	Adds a test that reserves the stream fast path, registers an onRenderFinished listener afterwards, asserts it hasn't run immediately, then calls setRenderFinished() and verifies the listener runs exactly once, followed by cleanup.
Changeset .changeset/cool-streams-close.md	Adds a changeset noting the patch-level fix: late-registered onRenderFinished listeners now run instead of being dropped, preventing SSR stream hangs.

Sequence Diagram(s)

sequenceDiagram
  participant SSRServer
  participant RouterSsrQueryIntegration
  participant QueryStream
  RouterSsrQueryIntegration->>SSRServer: reserveStreamFastPath()
  RouterSsrQueryIntegration->>SSRServer: onRenderFinished(register close callback)
  SSRServer->>QueryStream: setRenderFinished() (later)
  SSRServer->>RouterSsrQueryIntegration: invoke registered callback
  RouterSsrQueryIntegration->>QueryStream: close()

Loading

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~20 minutes

Suggested labels

package: router-core

Suggested reviewers

• schiller-manuel

Poem

A rabbit found a stalled stream,
Where quiet listeners lost their gleam.
It nudged the fast path, gave a hop,
Now late listeners run — no stop. 🐇✨

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title accurately and concisely summarizes the primary fix: preventing onRenderFinished listeners from being dropped when the stream fast path is reserved.
Linked Issues check	✅ Passed	The PR fully addresses all five coding requirements from #7529: identifies the root cause, restores listener behavior, enables SSR dehydration cleanup, prevents serialization timeout, and maintains compatibility.
Out of Scope Changes check	✅ Passed	All changes directly relate to fixing the onRenderFinished listener bug: the logic fix, changeset entry, and regression test are all in scope.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[coderabbitai]

Actionable comments posted: 1

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@packages/router-core/src/ssr/ssr-server.ts`:
- Line 640: The single-line guard "if (cleanupStarted) return" must use braces
to comply with the TypeScript coding guideline; locate the conditional using the
cleanupStarted variable (in the SSR shutdown/cleanup routine where
cleanupStarted is checked) and replace the single-line form with a braced block
(e.g., if (cleanupStarted) { return; }) so the control statement always uses
curly braces.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: 265c1e99-50a2-427c-b3ff-819c14e0feca

📥 Commits

Reviewing files that changed from the base of the PR and between ae9d550 and ad107d2.

📒 Files selected for processing (3)

• .changeset/cool-streams-close.md
• packages/router-core/src/ssr/ssr-server.ts
• packages/router-core/tests/ssr-server-cleanup.test.ts

✅ Files skipped from review due to trivial changes (1)

• .changeset/cool-streams-close.md