Skip to content

Commit 694b1e8

Browse files
committed
docs(router): warm rendered-barrier + why-web-streams; rendered() loading()-precision + #548 link [skip ci]
1 parent 68b96cf commit 694b1e8

2 files changed

Lines changed: 151 additions & 110 deletions

File tree

‎packages/rangojs-router/docs/internal/rendered-barrier.md‎

Lines changed: 58 additions & 28 deletions
Original file line numberDiff line numberDiff line change
@@ -2,21 +2,30 @@
22

33
**Status**: Experimental. Works in DSL loaders, including streaming trees that use `loading()` (the barrier waits for the streaming handlers to settle).
44

5-
## Problem
5+
If you're about to touch how loaders read handle data — or you just hit
6+
`ctx.rendered()` in a loader and want to know what it actually promises —
7+
start here. This is a small feature with a sharp edge, and the edge is exactly
8+
where the scar tissue lives.
69

7-
Loaders run before handlers. A loader that needs to know which data the
8-
handler tree produced (e.g., which product IDs were rendered) must either
9-
duplicate the fetch or create a loader-to-loader waterfall.
10+
## The problem it solves
1011

11-
Handles accumulate data from handlers/layouts for downstream consumption,
12-
but loaders cannot read handles because handles are populated after loaders
13-
start.
12+
Loaders run before handlers. That ordering is fine until a loader needs to know
13+
what the handler tree produced — say, which product IDs ended up rendered. With
14+
nothing to lean on, that loader has two bad options: duplicate the fetch the
15+
handler already did, or chain itself behind another loader and create a
16+
loader-to-loader waterfall. Neither is something you want to write twice.
1417

15-
## Solution
18+
Handles look like the natural answer — they exist precisely to accumulate data
19+
from handlers and layouts for downstream consumption. But there's a timing
20+
mismatch: handles are populated _after_ loaders start, so a loader that reads a
21+
handle reads it empty. The data it wants hasn't been written yet.
1622

17-
Add `await ctx.rendered()` to loader context. After the promise resolves,
18-
the non-loader render tree has settled and all handle data is available.
19-
The loader can then read handles via `ctx.use(handle)`.
23+
## The fix
24+
25+
Give the loader a way to wait. `await ctx.rendered()` is that wait: once the
26+
promise resolves, the non-loader render tree has settled and all handle data is
27+
in place. From there the loader can read handles via `ctx.use(handle)` and get
28+
real values.
2029

2130
```ts
2231
const PricesLoader = createLoader(async (ctx) => {
@@ -29,15 +38,22 @@ const PricesLoader = createLoader(async (ctx) => {
2938

3039
## Semantics
3140

41+
This is the contract you can rely on:
42+
3243
- `rendered()` returns a `Promise<void>` that resolves when all non-loader
3344
segments in the matched tree have settled and handle data is available.
3445
- After `await ctx.rendered()`, `ctx.use(handle)` returns the accumulated
3546
handle data (the collected value, same shape as `useHandle()` on client).
36-
- Before `await ctx.rendered()`, `ctx.use(handle)` throws.
47+
- Before `await ctx.rendered()`, `ctx.use(handle)` throws. (The handle isn't
48+
populated yet, so there's nothing correct to hand back — better to throw than
49+
to lie.)
3750
- `ctx.use(loader)` continues to work normally at any point.
3851
- `rendered()` is idempotent — multiple calls return the same promise.
3952

40-
## Phase 1 Scope
53+
## Phase 1 scope
54+
55+
This is the first cut, so the supported surface is deliberately narrow. Here's
56+
what's in.
4157

4258
### Supported
4359

@@ -51,7 +67,10 @@ const PricesLoader = createLoader(async (ctx) => {
5167
- Prerender replay: handles are replayed from build artifacts, barrier
5268
resolves immediately.
5369

54-
### Not Supported (Phase 1)
70+
### Not supported (Phase 1)
71+
72+
And here's what's intentionally out — each of these is a case we either couldn't
73+
make correct yet or chose not to chase:
5574

5675
- Handler-invoked loaders (`ctx.use(Loader)` inside a route/layout handler).
5776
Calling `rendered()` from a handler-invoked loader throws immediately.
@@ -60,21 +79,27 @@ const PricesLoader = createLoader(async (ctx) => {
6079
- Nested `rendered()` dependencies (loader A awaits rendered, loader B
6180
depends on loader A via `ctx.use(A)` — this works but is not optimized).
6281

63-
### Known Limitations
82+
### Known limitations
83+
84+
Two sharp edges to keep in mind. Both are real and both can bite quietly, so
85+
they're worth reading before you build on this:
6486

6587
- **Promise handle values**: `rendered()` guarantees the handler has
6688
executed and called `push()`, but does NOT guarantee that promise values
6789
inside pushes have resolved. If a handler does `push(fetchSomething())`,
6890
the loader will see the unresolved Promise object. Push synchronous
6991
values for Phase 1 correctness.
7092
- **Deadlock with handler ctx.use()**: If a loader calls `rendered()`, a
71-
handler must not `await ctx.use(thatSameLoader)`. The handler would block
72-
segment resolution, which blocks the barrier, which blocks the loader.
73-
A runtime check detects this when the loader has already called
74-
`rendered()` before the handler runs; timing-dependent cases may still
75-
deadlock without detection.
93+
handler must not `await ctx.use(thatSameLoader)` — the handler would block
94+
segment resolution, which blocks the barrier, which blocks the loader. The
95+
runtime guard catches this bidirectionally (whichever side runs first), and on
96+
streaming trees it stays live until `handleStore.settled`, so a `loading()`
97+
handler that resumes after the barrier is still caught. The cycle surfaces as
98+
an error instead of hanging.
99+
100+
## Guard rules
76101

77-
## Guard Rules
102+
When the guards fire and when they don't, in one table:
78103

79104
| Condition | Behavior |
80105
| ------------------------------------------------ | ----------------------------------------------------- |
@@ -85,11 +110,12 @@ const PricesLoader = createLoader(async (ctx) => {
85110
| `ctx.use(handle)` before `await ctx.rendered()` | Throws |
86111
| `ctx.use(handle)` after `await ctx.rendered()` | Returns collected handle data |
87112

88-
## Implementation Notes
113+
## Implementation notes
89114

90-
### Render Barrier Lifecycle
115+
### Render barrier lifecycle
91116

92-
The render barrier is a deferred promise on the request context:
117+
Under the hood the render barrier is a deferred promise on the request context.
118+
What resolves it depends on which path the request took:
93119

94120
- **Fresh path (non-streaming)**: Resolved after `resolveAllSegments()`
95121
returns. At that point all handlers have completed and all synchronous
@@ -108,7 +134,7 @@ The render barrier is a deferred promise on the request context:
108134
- **Prerender path**: Resolved after handle data is replayed from build
109135
artifacts. Same as cache hit.
110136

111-
### Loader `use(handle)` After Barrier
137+
### Loader `use(handle)` after barrier
112138

113139
After `rendered()` resolves, the loader's `ctx.use(handle)` reads from
114140
the HandleStore. The data is collected using the handle's `collect`
@@ -117,7 +143,7 @@ function (same as `useHandle()` on the client), producing the same shape.
117143
Segment order for collection follows the segment resolution order
118144
(parent → child), captured when the barrier resolves.
119145

120-
### How Streaming Works
146+
### How streaming works
121147

122148
In a streaming tree, handlers behind `loading()` have not finished pushing
123149
when `resolveAllSegments()` returns — only their _rendered output_ streams
@@ -136,10 +162,14 @@ none is unregistered; pushes happen _within_ those tracked promises (before
136162
`settled`); and the payload's later `stream()` auto-seal is idempotent.
137163

138164
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
165+
Known limitations) — `settled` waits for the handler to push, not for a pushed
140166
`Promise` to resolve.
141167

142-
## Stop Conditions
168+
## Stop conditions
169+
170+
If you're extending this, these are the lines that should make you stop and
171+
reconsider rather than push through — the points where the feature stops earning
172+
its complexity:
143173

144174
- Broad changes across render, cache, prerender, and streaming to support
145175
the basic case.

0 commit comments

Comments
 (0)