Skip to content

Commit 68b96cf

Browse files
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/rendered-barrier.md‎

Lines changed: 45 additions & 30 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
# Rendered Barrier (Experimental)
22

3-
**Status**: Phase 1 — experimental, non-streaming only.
3+
**Status**: Experimental. Works in DSL loaders, including streaming trees that use `loading()` (the barrier waits for the streaming handlers to settle).
44

55
## Problem
66

@@ -42,7 +42,9 @@ const PricesLoader = createLoader(async (ctx) => {
4242
### Supported
4343

4444
- DSL loaders only (registered via `loader()` in `urls()` trees).
45-
- Non-streaming render trees: no `loading()` on any entry in the matched tree.
45+
- Streaming trees (`loading()`): the streaming handlers' async execution is
46+
tracked in the handle store, so the barrier waits for them to finish pushing
47+
before it resolves — the loader then reads complete handle data.
4648
- Fresh SSR (full and partial match).
4749
- Cache hit replay (runtime cache): handles are replayed from cache, barrier
4850
resolves immediately.
@@ -53,8 +55,6 @@ const PricesLoader = createLoader(async (ctx) => {
5355

5456
- Handler-invoked loaders (`ctx.use(Loader)` inside a route/layout handler).
5557
Calling `rendered()` from a handler-invoked loader throws immediately.
56-
- Streaming trees: any entry with a `loading()` fallback causes `rendered()`
57-
to throw. `loading(false)` (streaming explicitly disabled) is fine.
5858
- Partial/revalidation special cases: no special handling beyond what falls
5959
out naturally from the cache-hit path.
6060
- Nested `rendered()` dependencies (loader A awaits rendered, loader B
@@ -76,25 +76,33 @@ const PricesLoader = createLoader(async (ctx) => {
7676

7777
## Guard Rules
7878

79-
| Condition | Behavior |
80-
| ------------------------------------------------ | ------------------------------ |
81-
| `rendered()` in DSL loader, no streaming | Resolves after handlers settle |
82-
| `rendered()` in DSL loader, tree has `loading()` | Throws `RenderedBarrierError` |
83-
| `rendered()` in handler-invoked loader | Throws `RenderedBarrierError` |
84-
| `ctx.use(handle)` before `await ctx.rendered()` | Throws |
85-
| `ctx.use(handle)` after `await ctx.rendered()` | Returns collected handle data |
79+
| Condition | Behavior |
80+
| ------------------------------------------------ | ----------------------------------------------------- |
81+
| `rendered()` in DSL loader, no streaming | Resolves after handlers settle |
82+
| `rendered()` in DSL loader, tree has `loading()` | Waits for streaming handlers to settle, then resolves |
83+
| `rendered()` in handler-invoked loader | Throws `RenderedBarrierError` |
84+
| `rendered()` while a handler awaits this loader | Throws (deadlock guard) |
85+
| `ctx.use(handle)` before `await ctx.rendered()` | Throws |
86+
| `ctx.use(handle)` after `await ctx.rendered()` | Returns collected handle data |
8687

8788
## Implementation Notes
8889

8990
### Render Barrier Lifecycle
9091

9192
The render barrier is a deferred promise on the request context:
9293

93-
- **Fresh path**: Resolved after `resolveAllSegments()` returns. At that
94-
point all handlers have completed (non-streaming guarantee) and all
95-
synchronous handle data has been pushed. The HandleStore is NOT sealed
96-
here — sealing stays in the existing lifecycle (rsc-rendering.ts,
97-
cache-scope.ts). Promise-valued handle pushes may still be unresolved.
94+
- **Fresh path (non-streaming)**: Resolved after `resolveAllSegments()`
95+
returns. At that point all handlers have completed and all synchronous
96+
handle data has been pushed.
97+
- **Fresh path (streaming, `loading()`)**: the barrier still resolves after
98+
`resolveAllSegments()`, but `loading()` handlers are still in flight then.
99+
Their async execution is tracked in the handle store (`trackHandler` →
100+
`store.track`), so `rendered()` additionally seals the store and `await`s
101+
`handleStore.settled` before resolving — every tracked handler, streaming
102+
included, has finished pushing. `ctx.use(handle)` then builds a fresh,
103+
complete snapshot. The loader's own segment streams in after, so this does
104+
not block the shell; the deadlock guard keeps a handler from depending on
105+
the loader. Promise-valued handle pushes may still be unresolved.
98106
- **Cache hit path**: Resolved after handle data is replayed from cache.
99107
Handles are immediately available.
100108
- **Prerender path**: Resolved after handle data is replayed from build
@@ -109,20 +117,27 @@ function (same as `useHandle()` on the client), producing the same shape.
109117
Segment order for collection follows the segment resolution order
110118
(parent → child), captured when the barrier resolves.
111119

112-
### Why Not Streaming (Phase 1)
113-
114-
In a streaming tree, handlers behind `loading()` may not have settled when
115-
`resolveAllSegments()` returns — their components are promises that resolve
116-
during RSC serialization. Handle data from those handlers would be
117-
incomplete at barrier resolution time.
118-
119-
Supporting streaming requires tracking which handles come from settled vs
120-
unsettled handlers and either:
121-
122-
- Waiting for full settlement (defeating streaming's purpose), or
123-
- Providing a partial snapshot with explicit "may be incomplete" semantics.
124-
125-
Both add complexity with unclear value. Phase 1 avoids this entirely.
120+
### How Streaming Works
121+
122+
In a streaming tree, handlers behind `loading()` have not finished pushing
123+
when `resolveAllSegments()` returns — only their _rendered output_ streams
124+
behind Suspense; the handler function itself runs eagerly and its async
125+
execution (including its `push()` calls) is tracked in the handle store
126+
(`fresh.ts`: `trackHandler(handler(context))` → `store.track`). So the signal
127+
"all handlers have pushed" already exists: `handleStore.settled` (sealed AND no
128+
in-flight tracked promises).
129+
130+
`rendered()` uses it. For a streaming tree it does not trust the eager snapshot
131+
built when the barrier resolves (incomplete — the `loading()` handlers were
132+
still in flight); instead it seals the store and `await`s `handleStore.settled`,
133+
then `ctx.use(handle)` builds a fresh, complete snapshot. The seal is safe
134+
because every handler is tracked during `resolveAllSegments`, so by barrier time
135+
none is unregistered; pushes happen _within_ those tracked promises (before
136+
`settled`); and the payload's later `stream()` auto-seal is idempotent.
137+
138+
The one thing this does NOT do is wait for promise _values_ inside pushes (see
139+
Known Limitations) — `settled` waits for the handler to push, not for a pushed
140+
`Promise` to resolve.
126141

127142
## Stop Conditions
128143

‎packages/rangojs-router/e2e/rendered-barrier.test.ts‎

Lines changed: 115 additions & 17 deletions
Original file line numberDiff line numberDiff line change
@@ -189,43 +189,141 @@ function renderedBarrierTests(mode: "dev" | "build") {
189189
);
190190
});
191191

192-
test("streaming tree: rendered() rejects with loading()", async ({
192+
test("streaming tree: rendered() waits for the loading() handler, then reads its data", async ({
193193
page,
194194
}) => {
195-
// rendered() throws inside the loader because the route has loading().
196-
// The error propagates through RSC and surfaces as either a page error
197-
// (pageerror event) or visible error UI (React error boundary / Vite
198-
// overlay). We assert BOTH that prices did not render AND that an error
199-
// signal was observed — ruling out a silent hang/deadlock.
195+
using _ = expectNoPageError(page);
196+
// The handler is behind loading() and pushes gadget-x/gadget-y only after
197+
// an await (during the streaming phase, past the render barrier). Before
198+
// the fix, rendered() threw here. Now it waits for the streaming handler
199+
// to settle, so the loader reads the pushed IDs and resolves their prices.
200+
await page.goto(f.url("/rendered-barrier/streaming"));
201+
await waitForHydration(page);
202+
203+
await expect(testId(page, "rendered-streaming-title")).toHaveText(
204+
"Streaming Products",
205+
);
206+
207+
// Prices loaded — proves the loader saw the handle data pushed during
208+
// streaming (an empty/early barrier would yield a count of 0).
209+
await expect(testId(page, "rendered-streaming-price-count")).toHaveText(
210+
"2",
211+
);
212+
await expect(
213+
testId(page, "rendered-streaming-price-gadget-x"),
214+
).toContainText("$49.99");
215+
await expect(
216+
testId(page, "rendered-streaming-price-gadget-y"),
217+
).toContainText("$99.99");
218+
});
219+
220+
test("streaming + cache hit: rendered() reads replayed handle data on the cached path", async ({
221+
page,
222+
}) => {
223+
using _ = expectNoPageError(page);
224+
// A loading() handler under cache(): the streamed handle push must be
225+
// captured into the cache on the miss and replayed on the hit, so the live
226+
// loader's rendered() reads it on the cache-hit path (not the empty live
227+
// store). First visit populates the cache.
228+
await page.goto(f.url("/rendered-barrier/streaming-cached"));
229+
await waitForHydration(page);
230+
await expect(testId(page, "rendered-streaming-cached-title")).toHaveText(
231+
"Streaming Cached",
232+
);
233+
const ts1 = await testId(
234+
page,
235+
"rendered-streaming-cached-ts",
236+
).textContent();
237+
await expect(
238+
testId(page, "rendered-streaming-cached-price-count"),
239+
).toHaveText("2");
240+
await expect(
241+
testId(page, "rendered-streaming-cached-price-widget-a"),
242+
).toContainText("$9.99");
243+
await expect(
244+
testId(page, "rendered-streaming-cached-price-widget-b"),
245+
).toContainText("$19.99");
246+
247+
await page.waitForTimeout(50);
248+
249+
// Second visit — cache HIT: handler (and its streamed handle data) replayed
250+
// from cache. The handler ts is unchanged; the live loader re-runs and its
251+
// rendered() reads the replayed handle data on the cache-hit path.
252+
await page.goto(f.url("/rendered-barrier/streaming-cached"));
253+
await waitForHydration(page);
254+
const ts2 = await testId(
255+
page,
256+
"rendered-streaming-cached-ts",
257+
).textContent();
258+
expect(ts1).toBe(ts2);
259+
await expect(
260+
testId(page, "rendered-streaming-cached-price-count"),
261+
).toHaveText("2");
262+
await expect(
263+
testId(page, "rendered-streaming-cached-price-widget-a"),
264+
).toContainText("$9.99");
265+
await expect(
266+
testId(page, "rendered-streaming-cached-price-widget-b"),
267+
).toContainText("$19.99");
268+
});
269+
270+
test("streaming + prerender replay: rendered() reads replayed handle data", async ({
271+
page,
272+
}) => {
273+
using _ = expectNoPageError(page);
274+
// A loading() handler that is build-time prerendered. At runtime the
275+
// handler output and its streamed handle data are replayed; the live
276+
// loader's rendered() must read the replayed data on the prerender path.
277+
await page.goto(f.url("/rendered-barrier/streaming-prerender"));
278+
await waitForHydration(page);
279+
await expect(
280+
testId(page, "rendered-streaming-prerender-title"),
281+
).toHaveText("Streaming Prerender");
282+
await expect(
283+
testId(page, "rendered-streaming-prerender-price-count"),
284+
).toHaveText("2");
285+
await expect(
286+
testId(page, "rendered-streaming-prerender-price-widget-a"),
287+
).toContainText("$9.99");
288+
await expect(
289+
testId(page, "rendered-streaming-prerender-price-widget-c"),
290+
).toContainText("$29.99");
291+
});
292+
293+
test("streaming deadlock: handler awaiting a rendered() loader errors, does not hang", async ({
294+
page,
295+
}) => {
296+
// A loading() handler awaits a loader that calls rendered() — a cycle.
297+
// The deadlock guard must surface an error rather than hang, even though
298+
// rendered() keeps waiting on handleStore.settled AFTER the barrier
299+
// resolves. We assert the success title did NOT render and that an error
300+
// signal is present; a regression that reopened the deadlock would instead
301+
// time this test out.
200302
const errors: string[] = [];
201303
page.on("pageerror", (error) => errors.push(error.message));
202304

203305
const response = await page.goto(
204-
f.url("/rendered-barrier/streaming-rejected"),
306+
f.url("/rendered-barrier/streaming-deadlock"),
205307
);
206-
await page.waitForTimeout(3000);
308+
await page.waitForTimeout(2000);
207309

208-
// Prices must NOT have rendered
209-
const pricesVisible = await testId(page, "rendered-streaming-prices")
310+
const titleVisible = await testId(page, "rendered-deadlock-title")
210311
.isVisible()
211312
.catch(() => false);
212-
expect(pricesVisible).toBe(false);
313+
expect(titleVisible).toBe(false);
213314

214-
// At least one error signal must be present: page error event,
215-
// non-200 response, or visible error text in the DOM.
216315
const hasPageError = errors.length > 0;
217316
const hasErrorStatus = response !== null && response.status() >= 400;
218317
const hasErrorText = await page
219318
.locator("text=/error/i")
220319
.first()
221320
.isVisible({ timeout: 1000 })
222321
.catch(() => false);
223-
224322
expect(
225323
hasPageError || hasErrorStatus || hasErrorText,
226-
`Expected an error signal from rendered() rejection, but got none. ` +
227-
`Page errors: ${errors.length}, status: ${response?.status()}, ` +
228-
`error text visible: ${hasErrorText}`,
324+
`Expected a deadlock error signal, got none. ` +
325+
`pageErrors=${errors.length}, status=${response?.status()}, ` +
326+
`errorText=${hasErrorText}`,
229327
).toBe(true);
230328
});
231329
});

‎packages/rangojs-router/e2e/test-app/src/router.named-routes.gen.ts‎

Lines changed: 4 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -249,7 +249,10 @@ export const NamedRoutes = {
249249
"renderedBarrier.cached": "/rendered-barrier/cached",
250250
"renderedBarrier.fresh": "/rendered-barrier/fresh",
251251
"renderedBarrier.prerender": "/rendered-barrier/prerender",
252-
"renderedBarrier.streamingRejected": "/rendered-barrier/streaming-rejected",
252+
"renderedBarrier.streaming": "/rendered-barrier/streaming",
253+
"renderedBarrier.streamingCached": "/rendered-barrier/streaming-cached",
254+
"renderedBarrier.streamingDeadlock": "/rendered-barrier/streaming-deadlock",
255+
"renderedBarrier.streamingPrerender": "/rendered-barrier/streaming-prerender",
253256
"renderedBarrier.useCache": "/rendered-barrier/use-cache",
254257
"responseCache.responseCache.html": "/response-cache/cached-html",
255258
"responseCache.responseCache.json": "/response-cache/cached-json",

0 commit comments

Comments
 (0)