Repository navigation
Commit 68b96cf
authored
feat(router): support ctx.rendered() on streaming (loading()) trees (#553)
* feat(router): support ctx.rendered() on streaming (loading()) trees (#548)
Completes the render-barrier feature: a DSL loader can now `await ctx.rendered()`
and read handle data on a route tree that uses `loading()`, instead of the call
throwing. Closes #548.
The key realization is that the signal already exists. A loading() handler runs
EAGERLY — only its rendered output streams behind Suspense — and its full async
execution (including its push() calls) is tracked in the handle store
(fresh.ts: trackHandler(handler(context)) -> store.track). So handleStore.settled
(sealed AND no in-flight tracked promises) already waits for streaming handlers.
The only bug was that the barrier resolved synchronously right after
resolveAllSegments(), building an incomplete handle snapshot while those handlers
were still in flight.
Change (loader-resolution.ts), minimal blast radius:
- Remove the `_treeHasStreaming` reject guard.
- rendered(): for streaming trees, after the barrier resolves, seal the handle
store and `await handleStore.settled` before resolving. The seal is safe — every
handler is tracked during resolveAllSegments, so none is unregistered by barrier
time; pushes happen within those tracked promises (before settled); the payload's
later stream() auto-seal is idempotent.
- ctx.use(handle): for streaming trees build a fresh snapshot from the now-complete
store (the eager barrier snapshot is incomplete for streaming).
- Keep the handler-awaits-loader deadlock guard (the real cycle guard) and the
handler-invoked-loader guard.
- Non-streaming path is byte-for-byte unchanged.
Tests:
- Unit (rendered-barrier.test.ts): streaming tree now waits for a loading()
handler's deferred push and reads complete data; deadlock guard still rejects.
- E2e (rendered-barrier.test.ts, dev + production): repurposed the old
"streaming-rejected" route into "/streaming" — a loading() handler that pushes
its handle data AFTER an await (during streaming, past the barrier); the loader
reads it and resolves prices. Verified the semantic matrix stays green in both
modes.
Docs: rendered-barrier.md status/scope/guard-table updated; "Why Not Streaming"
reframed to "How Streaming Works". loader-types.ts rendered() doc drops the
non-streaming restriction. router.named-routes.gen.ts updated for the route rename.
* fix(router): keep rendered() deadlock guard live during the streaming settle wait
Review P1: on a streaming tree, rendered() keeps waiting on handleStore.settled
AFTER the render barrier resolves — but _resolveRenderBarrier tore down the guard
state (_renderBarrierWaiters / _handlerLoaderDeps) and the handler-side dependency
tracking went dark once _renderBarrierSegmentOrder was set, both at barrier time.
So a loading() handler could resume during that wait, `await ctx.use(theSameLoader)`
undetected, and deadlock (the handler waits for the loader; the loader waits for
settled, which waits for the handler). That violated the "handler awaits the same
loader throws" contract.
Fix:
- request-context.ts _resolveRenderBarrier: for streaming trees, do NOT clear the
guard state at barrier time. Keep it live and tear it down on handleStore.settled
(by then every tracked handler has finished — none can await a loader anymore).
Non-streaming is unchanged (clears immediately). Added _renderBarrierGuardClosed.
- loader-resolution.ts: gate the Direction-2 dependency tracking on
_renderBarrierGuardClosed instead of _renderBarrierSegmentOrder, so it stays live
across the streaming settle wait. Direction-1 now sees the kept waiters.
Tests:
- Unit (rendered-barrier.test.ts): the mock _resolveRenderBarrier now MIRRORS the
real cleanup (immediate for non-streaming, settled-deferred for streaming). New
regression: a handler that awaits a still-waiting rendered() loader DURING the
streaming settle window throws (goes silent without the fix). 19/19.
- E2e (rendered-barrier.test.ts, dev + production): new /streaming-deadlock route —
a loading() handler awaits a rendered() loader; the guard must error, not hang
(a regression would time the test out). DeadlockLoader is `export const` so the
expose-internal-ids transform injects its $$id (the guard keys on loader.$$id).
- Semantic matrix green; router.named-routes.gen.ts updated for the new route.
* fix(router): exempt async push-callback continuations from the streaming deadlock guard
Review P2: the handler-to-loader deadlock guard used a plain `insideHandlePush`
boolean that is only true during a push callback's SYNCHRONOUS call. After an
async push callback's first await it resumes with the flag false. Before the P1
fix that was harmless (the guard window closed at the barrier), but P1 keeps
_renderBarrierWaiters live until handleStore.settled on streaming trees — so a
callback like push(async () => { await x; return ctx.use(RenderedLoader); }) that
resumes during the settle window would throw a false "Deadlock". A pushed promise
value is not tracked by settled and cannot block segment resolution, so it is not
a real cycle.
Fix:
- server/context.ts: add a push-callback ALS scope (runInsidePushCallbackScope /
isInsidePushCallbackScope), mirroring the loader-scope ALS. Unlike a boolean, it
survives the callback's awaits.
- loader-resolution.ts: run the push callback inside runInsidePushCallbackScope and
gate the deadlock guard on isInsidePushCallbackScope() instead of the removed
boolean — so an async callback's continuation stays exempt.
Tests:
- Unit (rendered-barrier.test.ts): streaming counterpart of the existing
"push callback resumes after barrier" test — an async push callback that calls
ctx.use(loader) DURING the streaming settle window must NOT throw. The mock pulls
the REAL push-callback ALS via importActual so scope-survives-await is exercised
faithfully (it throws without the fix). 20/20.
- Updated loader-cycle-detection.test.ts's context mock with the two new exports.
- Full unit (3386), e2e rendered-barrier dev + production (8/8 each), semantic
matrix green.
* refactor(router): tidy streaming rendered() per /simplify review
Cleanup pass over the streaming rendered() changes (no behavior change):
- Cache the streaming handle snapshot once. rendered() now builds the complete
snapshot after handleStore.settled and stores it in _renderBarrierHandleSnapshot,
so ctx.use(handle) reads the cached snapshot uniformly instead of rebuilding it
on every call for streaming trees. This also collapses the _treeHasStreaming
ternary in ctx.use(handle) to a single `cached ?? buildHandleSnapshot(...)`
expression — the snapshot's presence is now the only signal, with streaming vs
non-streaming living solely at the point that decides when to populate it.
- Extract a closeGuard() closure in _resolveRenderBarrier so the three-line guard
teardown is written once; the only streaming/non-streaming difference left is
WHEN it runs (now vs. settled.then(closeGuard)).
- Fix stale comments that referenced the removed `insideHandlePush` boolean
(now the isInsidePushCallbackScope() ALS scope), in loader-resolution.ts and the
push-callback unit test.
Verified: typecheck, full unit (3386), rendered-barrier e2e dev + production (8/8
each), lint, format.
* test(router): cover rendered() on streaming + cache-hit / prerender-replay
Closes the one rendered()-under-streaming path that was asserted only by
reasoning (flagged in the PR review): a loading() tree whose handler output and
streamed handle data are REPLAYED (runtime cache hit, or build-time prerender),
where the live loader calls rendered() on the replay path.
Two new test-app routes + e2e (dev + production):
- /streaming-cached — loading() handler under cache(). First request renders
fresh (streaming, deferred push); the second is a cache HIT. Asserts the
handler ts is unchanged (cached) and the live loader's rendered() still reads
the replayed handle data (widget-a/widget-b prices), proving the cache captured
the streamed push and replay feeds rendered() correctly.
- /streaming-prerender — loading() handler that is build-time prerendered (build
log confirms `[rango] OK /rendered-barrier/streaming-prerender`). At runtime
the replayed handle data feeds the live loader's rendered().
Both verified green in dev and production; full rendered-barrier suite now 10/10
each mode. router.named-routes.gen.ts updated for the two routes.
* docs(skill): note ctx.rendered() works under loading() streaming [skip ci]
The loader skill is the only consumer-facing doc for ctx.rendered(); its row
predated streaming support and didn't say whether loading() was safe. Update it
to state that rendered() waits for all non-loader segments — including loading()
streaming handlers — to settle before handle data is readable.
Markdown only (oxfmt re-aligned the Loader Context table). The internal contract
doc (docs/internal/rendered-barrier.md) and the loader-types.ts JSDoc were
already updated in this PR; feature-map/feature-file-map need no change (no new
source files, and the new ALS helpers are module-internal, not public exports).1 parent cd29a23 commit 68b96cf
11 files changed
Lines changed: 699 additions & 141 deletions
File tree
- packages/rangojs-router
- docs/internal
- e2e
- test-app/src
- urls
- skills/loader
- src
- router
- __tests__
- server
- types
| Original file line number | Diff line number | Diff line change | |
|---|---|---|---|
| |||
1 | 1 | | |
2 | 2 | | |
3 | | - | |
| 3 | + | |
4 | 4 | | |
5 | 5 | | |
6 | 6 | | |
| |||
42 | 42 | | |
43 | 43 | | |
44 | 44 | | |
45 | | - | |
| 45 | + | |
| 46 | + | |
| 47 | + | |
46 | 48 | | |
47 | 49 | | |
48 | 50 | | |
| |||
53 | 55 | | |
54 | 56 | | |
55 | 57 | | |
56 | | - | |
57 | | - | |
58 | 58 | | |
59 | 59 | | |
60 | 60 | | |
| |||
76 | 76 | | |
77 | 77 | | |
78 | 78 | | |
79 | | - | |
80 | | - | |
81 | | - | |
82 | | - | |
83 | | - | |
84 | | - | |
85 | | - | |
| 79 | + | |
| 80 | + | |
| 81 | + | |
| 82 | + | |
| 83 | + | |
| 84 | + | |
| 85 | + | |
| 86 | + | |
86 | 87 | | |
87 | 88 | | |
88 | 89 | | |
89 | 90 | | |
90 | 91 | | |
91 | 92 | | |
92 | 93 | | |
93 | | - | |
94 | | - | |
95 | | - | |
96 | | - | |
97 | | - | |
| 94 | + | |
| 95 | + | |
| 96 | + | |
| 97 | + | |
| 98 | + | |
| 99 | + | |
| 100 | + | |
| 101 | + | |
| 102 | + | |
| 103 | + | |
| 104 | + | |
| 105 | + | |
98 | 106 | | |
99 | 107 | | |
100 | 108 | | |
| |||
109 | 117 | | |
110 | 118 | | |
111 | 119 | | |
112 | | - | |
113 | | - | |
114 | | - | |
115 | | - | |
116 | | - | |
117 | | - | |
118 | | - | |
119 | | - | |
120 | | - | |
121 | | - | |
122 | | - | |
123 | | - | |
124 | | - | |
125 | | - | |
| 120 | + | |
| 121 | + | |
| 122 | + | |
| 123 | + | |
| 124 | + | |
| 125 | + | |
| 126 | + | |
| 127 | + | |
| 128 | + | |
| 129 | + | |
| 130 | + | |
| 131 | + | |
| 132 | + | |
| 133 | + | |
| 134 | + | |
| 135 | + | |
| 136 | + | |
| 137 | + | |
| 138 | + | |
| 139 | + | |
| 140 | + | |
126 | 141 | | |
127 | 142 | | |
128 | 143 | | |
| |||
| Original file line number | Diff line number | Diff line change | |
|---|---|---|---|
| |||
189 | 189 | | |
190 | 190 | | |
191 | 191 | | |
192 | | - | |
| 192 | + | |
193 | 193 | | |
194 | 194 | | |
195 | | - | |
196 | | - | |
197 | | - | |
198 | | - | |
199 | | - | |
| 195 | + | |
| 196 | + | |
| 197 | + | |
| 198 | + | |
| 199 | + | |
| 200 | + | |
| 201 | + | |
| 202 | + | |
| 203 | + | |
| 204 | + | |
| 205 | + | |
| 206 | + | |
| 207 | + | |
| 208 | + | |
| 209 | + | |
| 210 | + | |
| 211 | + | |
| 212 | + | |
| 213 | + | |
| 214 | + | |
| 215 | + | |
| 216 | + | |
| 217 | + | |
| 218 | + | |
| 219 | + | |
| 220 | + | |
| 221 | + | |
| 222 | + | |
| 223 | + | |
| 224 | + | |
| 225 | + | |
| 226 | + | |
| 227 | + | |
| 228 | + | |
| 229 | + | |
| 230 | + | |
| 231 | + | |
| 232 | + | |
| 233 | + | |
| 234 | + | |
| 235 | + | |
| 236 | + | |
| 237 | + | |
| 238 | + | |
| 239 | + | |
| 240 | + | |
| 241 | + | |
| 242 | + | |
| 243 | + | |
| 244 | + | |
| 245 | + | |
| 246 | + | |
| 247 | + | |
| 248 | + | |
| 249 | + | |
| 250 | + | |
| 251 | + | |
| 252 | + | |
| 253 | + | |
| 254 | + | |
| 255 | + | |
| 256 | + | |
| 257 | + | |
| 258 | + | |
| 259 | + | |
| 260 | + | |
| 261 | + | |
| 262 | + | |
| 263 | + | |
| 264 | + | |
| 265 | + | |
| 266 | + | |
| 267 | + | |
| 268 | + | |
| 269 | + | |
| 270 | + | |
| 271 | + | |
| 272 | + | |
| 273 | + | |
| 274 | + | |
| 275 | + | |
| 276 | + | |
| 277 | + | |
| 278 | + | |
| 279 | + | |
| 280 | + | |
| 281 | + | |
| 282 | + | |
| 283 | + | |
| 284 | + | |
| 285 | + | |
| 286 | + | |
| 287 | + | |
| 288 | + | |
| 289 | + | |
| 290 | + | |
| 291 | + | |
| 292 | + | |
| 293 | + | |
| 294 | + | |
| 295 | + | |
| 296 | + | |
| 297 | + | |
| 298 | + | |
| 299 | + | |
| 300 | + | |
| 301 | + | |
200 | 302 | | |
201 | 303 | | |
202 | 304 | | |
203 | 305 | | |
204 | | - | |
| 306 | + | |
205 | 307 | | |
206 | | - | |
| 308 | + | |
207 | 309 | | |
208 | | - | |
209 | | - | |
| 310 | + | |
210 | 311 | | |
211 | 312 | | |
212 | | - | |
| 313 | + | |
213 | 314 | | |
214 | | - | |
215 | | - | |
216 | 315 | | |
217 | 316 | | |
218 | 317 | | |
219 | 318 | | |
220 | 319 | | |
221 | 320 | | |
222 | 321 | | |
223 | | - | |
224 | 322 | | |
225 | 323 | | |
226 | | - | |
227 | | - | |
228 | | - | |
| 324 | + | |
| 325 | + | |
| 326 | + | |
229 | 327 | | |
230 | 328 | | |
231 | 329 | | |
| |||
| Original file line number | Diff line number | Diff line change | |
|---|---|---|---|
| |||
249 | 249 | | |
250 | 250 | | |
251 | 251 | | |
252 | | - | |
| 252 | + | |
| 253 | + | |
| 254 | + | |
| 255 | + | |
253 | 256 | | |
254 | 257 | | |
255 | 258 | | |
| |||
0 commit comments