Skip to content

Commit f513771

Browse files
Rework the flight-entry age gate: stamp adopted entries at boot, not consumption — the blanket CACHE_TIMEOUT bound still seeded the entry fetched-now, so a payload up to 180s old gained preload-grade freshness on any navigation; the entry now carries the payload's true age (its data is a fetch the server performed at render time) and the first consumption asks what the reuse condition would ask of a boot-time fetch: hydration/claim reads (no navigation in flight) adopt at any age since the server DOM was rendered from this exact value (#2964), back/forward honors the cache's 180s retention bar, and an active navigation or preload accepts only a payload young enough that a real preload would still satisfy it (PRELOAD_TIMEOUT), refetching otherwise
Co-authored-by: Cursor <[email protected]>
1 parent 3daa4d0 commit f513771

3 files changed

Lines changed: 252 additions & 57 deletions

File tree

‎.changeset/flight-entry-consumption-age-gate.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -2,4 +2,4 @@
22
"@solidjs/router": patch
33
---
44

5-
Bound hydration flight-entry adoption by the cache's own retention tolerance. `query()`'s keyed consumption path (`sharedConfig.has/load`) deliberately stays open past hydration `done` — a boundary inside a deferred claim scope (a lazy route module) can make its first call late and must adopt the promise the server DOM was rendered from — but adoption also stamps the seeded entry fresh (`cached[0] = now`, the burst-dedup window that lets preload + render share one consumption), so an entry first consumed long after load presented a minutes-old server value as fetched-now, masking its real age from the staleness logic entirely. Consumption is now gated on the flight payload being younger than `CACHE_TIMEOUT` (180s, the same bar the sweep applies to entries the router fetched itself): within the window behavior is unchanged, past it a first-ever call refetches instead of adopting.
5+
Slot hydration flight-entry adoption into the cache's freshness model instead of granting it fetched-now freshness. `query()`'s keyed consumption path (`sharedConfig.has/load`) deliberately stays open past hydration `done` — a boundary inside a deferred claim scope (a lazy route module) can make its first call late and must adopt the promise the server DOM was rendered from (#2964) — but adoption used to stamp the seeded entry fresh, so a payload consumed on a client-side navigation minutes after load masqueraded as just-fetched for the staleness logic. The adopted payload is now treated as a fetch performed at boot: the entry is stamped with the payload's age (not consumption time), and adoption itself is gated per navigation intent — hydration and late claim reads (no navigation in flight) adopt at any age since server-DOM consistency wins; back/forward restores honor the payload within `CACHE_TIMEOUT` (180s, the cache's own retention bar); an active new navigation or preload accepts it only within `PRELOAD_TIMEOUT` (5s), exactly the window a real preload would get, and refetches otherwise. The hydration render burst still dedups through the normal window/count reuse (it happens within milliseconds of boot), and a preloaded-then-abandoned payload no longer satisfies a navigation that comes along after the window.

‎src/data/query.ts‎

Lines changed: 32 additions & 14 deletions
Original file line numberDiff line numberDiff line change
@@ -163,31 +163,49 @@ export function query<T extends (...args: any) => any>(fn: T, name: string): Cac
163163
return res;
164164
}
165165
let res;
166+
let adopted = false;
166167
// Flight entries stay consumable past hydration `done` on purpose — a
167168
// boundary inside a deferred claim scope (a lazy route module) can
168169
// legitimately make its first query() call after global hydration reads
169-
// as done, and must adopt the promise the server DOM was rendered from.
170-
// But the entry gets stamped fresh on adoption (the burst-dedup window
171-
// below), so consumption is only honest while the payload is no older
172-
// than the cache's own retention tolerance: past CACHE_TIMEOUT an entry
173-
// the router had fetched itself would already have been swept, so a
174-
// first-ever call that late (idle tab, late navigation) refetches
175-
// instead of presenting a minutes-old value as fetched-now.
176-
if (!isServer && sharedConfig.has && sharedConfig.has(key) && now - bootTime < CACHE_TIMEOUT) {
177-
res = sharedConfig.load!(key) // hydrating
178-
// @ts-ignore at least until we add a delete method to sharedConfig
179-
delete globalThis._$HY.r[key];
180-
} else res = fn(...(args as any));
170+
// as done, and must adopt the promise the server DOM was rendered from
171+
// (#2964). Adoption slots into the cache's own freshness model as a
172+
// fetch that happened at boot: outside a navigation (no intent — the
173+
// hydration/claim case) DOM consistency wins at any age; a back/forward
174+
// restore honors the payload within the cache's retention window, the
175+
// same bar the sweep applies to entries the router fetched itself; an
176+
// active navigation (or its preload) accepts the payload only while a
177+
// real preload of the same age would still satisfy it — anything older
178+
// refetches instead of serving a minutes-old value on a fresh navigation.
179+
if (!isServer && sharedConfig.has && sharedConfig.has(key)) {
180+
const payloadAge = now - bootTime;
181+
if (!intent || payloadAge < (intent === "native" ? CACHE_TIMEOUT : PRELOAD_TIMEOUT)) {
182+
adopted = true;
183+
res = sharedConfig.load!(key); // hydrating
184+
// @ts-ignore at least until we add a delete method to sharedConfig
185+
delete globalThis._$HY.r[key];
186+
}
187+
// A payload too old for this intent stays in the registry: it is
188+
// inert while the refetched entry below lives, but a later claim
189+
// read (no intent) may still need it for server-DOM consistency.
190+
}
191+
if (!adopted) res = fn(...(args as any));
181192

193+
// Adopted entries are stamped at boot — when their data was actually
194+
// fetched — not at consumption. The hydration render burst still dedups
195+
// through the normal window/count reuse above (it happens within
196+
// milliseconds of boot), while a navigation that comes along later sees
197+
// the payload's true age and refetches past PRELOAD_TIMEOUT, exactly as
198+
// it would for a preload performed when the server fetched the data.
199+
const stamp = adopted ? bootTime : now;
182200
if (cached) {
183-
cached[0] = now;
201+
cached[0] = stamp;
184202
cached[1] = res;
185203
cached[3] = intent;
186204
!isServer && intent === "navigate" && cached[4][1](cached[0]); // update version
187205
} else {
188206
cache.set(
189207
key,
190-
(cached = [now, res, , intent, createSignal(now, { ownedWrite: true }) as Signal<number> & { count: number }])
208+
(cached = [stamp, res, , intent, createSignal(stamp, { ownedWrite: true }) as Signal<number> & { count: number }])
191209
);
192210
cached[4].count = 0;
193211
}

‎test/data/query-flight-consumption.spec.ts‎

Lines changed: 219 additions & 42 deletions
Original file line numberDiff line numberDiff line change
@@ -2,16 +2,24 @@ import { createRoot, sharedConfig } from "solid-js";
22
import { vi } from "vitest";
33
import { query } from "../../src/data/query.js";
44
import { createMockRouter } from "../helpers.js";
5+
import type { Intent } from "../../src/types.js";
56

67
const mockRouter = createMockRouter();
78

89
// query() only needs the intent/preload accessors and (behind an owner) useRouter.
10+
// Intent is mutable so each test can read through the path it is exercising:
11+
// undefined = hydration / late claim (no navigation in flight), "navigate" /
12+
// "preload" = an active new navigation, "native" = back/forward traversal.
13+
let currentIntent: Intent | undefined;
914
vi.mock("../../src/routing.js", () => ({
1015
useRouter: () => mockRouter,
11-
getIntent: () => "navigate",
16+
getIntent: () => currentIntent,
1217
getInPreloadFn: () => false
1318
}));
1419

20+
const PRELOAD_TIMEOUT = 5000;
21+
const CACHE_TIMEOUT = 180000;
22+
1523
// The client-side keyed consumption path (sharedConfig.has/load -> cache
1624
// seeding). The registry is seeded the way hydrate() leaves it: `_$HY.r`
1725
// holding the seroval-revived promise, sharedConfig.has/load reading it.
@@ -21,9 +29,15 @@ function seedFlightEntry(key: string, value: any) {
2129
sharedConfig.load = k => (globalThis as any)._$HY.r[k];
2230
}
2331

24-
describe("hydration flight-entry consumption", () => {
32+
function advanceClock(ms: number) {
33+
vi.useFakeTimers();
34+
vi.setSystemTime(Date.now() + ms);
35+
}
36+
37+
describe("query cache freshness windows", () => {
2538
beforeEach(() => {
2639
query.clear();
40+
currentIntent = undefined;
2741
});
2842

2943
afterEach(() => {
@@ -33,49 +47,212 @@ describe("hydration flight-entry consumption", () => {
3347
vi.useRealTimers();
3448
});
3549

36-
test("adopts a flight entry consumed while the payload is current, one-shot", async () => {
37-
return createRoot(async () => {
38-
seedFlightEntry("flightQuery[]", "server-data");
39-
let callCount = 0;
40-
const cachedFn = query(async () => {
41-
callCount++;
42-
return "fresh-data";
43-
}, "flightQuery");
44-
45-
// First call adopts the server value instead of fetching...
46-
const adopted = await cachedFn();
47-
expect(adopted).toBe("server-data");
48-
expect(callCount).toBe(0);
49-
// ...consumption is one-shot (the raw registry entry is deleted)...
50-
expect("flightQuery[]" in (globalThis as any)._$HY.r).toBe(false);
51-
// ...and the seeded cache entry replays for the consumption burst
52-
// (preload + render call the same key back to back).
53-
const replayed = await cachedFn();
54-
expect(replayed).toBe("server-data");
55-
expect(callCount).toBe(0);
50+
describe("preload preservation (non-flight)", () => {
51+
test("a preload within PRELOAD_TIMEOUT satisfies the navigation", async () => {
52+
return createRoot(async () => {
53+
let callCount = 0;
54+
const cachedFn = query(async () => {
55+
callCount++;
56+
return "data-" + callCount;
57+
}, "preloadFresh");
58+
59+
currentIntent = "preload";
60+
await cachedFn();
61+
expect(callCount).toBe(1);
62+
63+
// Navigate right away: the preloaded entry is inside the short
64+
// window and satisfies the navigation without a second fetch.
65+
currentIntent = "navigate";
66+
const result = await cachedFn();
67+
expect(result).toBe("data-1");
68+
expect(callCount).toBe(1);
69+
});
70+
});
71+
72+
test("a preload older than PRELOAD_TIMEOUT refetches on navigation", async () => {
73+
return createRoot(async () => {
74+
let callCount = 0;
75+
const cachedFn = query(async () => {
76+
callCount++;
77+
return "data-" + callCount;
78+
}, "preloadStale");
79+
80+
currentIntent = "preload";
81+
await cachedFn();
82+
expect(callCount).toBe(1);
83+
84+
// The user hovered, then thought about it: past the short window
85+
// the preserved preload no longer satisfies a new navigation.
86+
advanceClock(PRELOAD_TIMEOUT + 1000);
87+
currentIntent = "navigate";
88+
const result = await cachedFn();
89+
expect(result).toBe("data-2");
90+
expect(callCount).toBe(2);
91+
});
5692
});
5793
});
5894

59-
test("a flight entry first consumed long after load is stale — refetch, don't adopt", async () => {
60-
return createRoot(async () => {
61-
seedFlightEntry("lateQuery[]", "stale-server-data");
62-
let callCount = 0;
63-
const cachedFn = query(async () => {
64-
callCount++;
65-
return "fresh-data";
66-
}, "lateQuery");
67-
68-
// The entry arrived with the page, but nothing consumed it until long
69-
// past the cache's own retention tolerance (CACHE_TIMEOUT, 180s) — an
70-
// idle tab, a late client-side navigation. The serialized value is
71-
// minutes old; adopting it and stamping it fresh would mask its age
72-
// from query()'s staleness logic entirely.
73-
vi.useFakeTimers();
74-
vi.setSystemTime(Date.now() + 10 * 60 * 1000);
75-
76-
const result = await cachedFn();
77-
expect(result).toBe("fresh-data");
78-
expect(callCount).toBe(1);
95+
describe("hydration flight-entry consumption", () => {
96+
test("hydration burst adopts the flight entry and dedups, one-shot registry", async () => {
97+
return createRoot(async () => {
98+
seedFlightEntry("flightQuery[]", "server-data");
99+
let callCount = 0;
100+
const cachedFn = query(async () => {
101+
callCount++;
102+
return "fresh-data";
103+
}, "flightQuery");
104+
105+
// First call adopts the server value instead of fetching...
106+
const adopted = await cachedFn();
107+
expect(adopted).toBe("server-data");
108+
expect(callCount).toBe(0);
109+
// ...consumption is one-shot (the raw registry entry is deleted)...
110+
expect("flightQuery[]" in (globalThis as any)._$HY.r).toBe(false);
111+
// ...and the seeded cache entry replays for the consumption burst
112+
// (preload + render call the same key back to back).
113+
const replayed = await cachedFn();
114+
expect(replayed).toBe("server-data");
115+
expect(callCount).toBe(0);
116+
});
117+
});
118+
119+
test("a late lazy-boundary claim (no navigation) adopts at any age", async () => {
120+
return createRoot(async () => {
121+
seedFlightEntry("lateClaim[]", "server-data");
122+
let callCount = 0;
123+
const cachedFn = query(async () => {
124+
callCount++;
125+
return "fresh-data";
126+
}, "lateClaim");
127+
128+
// A boundary inside a deferred claim scope (lazy route module)
129+
// hydrates minutes after stream close (#2964 pattern). No
130+
// navigation is in flight, and the server DOM was rendered from
131+
// this exact value — adoption must still happen for consistency.
132+
advanceClock(10 * 60 * 1000);
133+
currentIntent = undefined;
134+
const result = await cachedFn();
135+
expect(result).toBe("server-data");
136+
expect(callCount).toBe(0);
137+
});
138+
});
139+
140+
test("a new navigation refetches instead of adopting an old payload", async () => {
141+
return createRoot(async () => {
142+
seedFlightEntry("staleNavigate[]", "stale-server-data");
143+
let callCount = 0;
144+
const cachedFn = query(async () => {
145+
callCount++;
146+
return "fresh-data";
147+
}, "staleNavigate");
148+
149+
// First-ever consumption comes from an active new navigation well
150+
// past the short window: the payload is not preload-fresh, so the
151+
// navigation fetches instead of presenting an old value as current.
152+
advanceClock(10 * 60 * 1000);
153+
currentIntent = "navigate";
154+
const result = await cachedFn();
155+
expect(result).toBe("fresh-data");
156+
expect(callCount).toBe(1);
157+
});
158+
});
159+
160+
test("a new navigation adopts a payload still inside the short window", async () => {
161+
return createRoot(async () => {
162+
seedFlightEntry("youngNavigate[]", "server-data");
163+
let callCount = 0;
164+
const cachedFn = query(async () => {
165+
callCount++;
166+
return "fresh-data";
167+
}, "youngNavigate");
168+
169+
currentIntent = "navigate";
170+
const result = await cachedFn();
171+
expect(result).toBe("server-data");
172+
expect(callCount).toBe(0);
173+
});
174+
});
175+
176+
test("back/forward adopts within CACHE_TIMEOUT", async () => {
177+
return createRoot(async () => {
178+
seedFlightEntry("nativeRestore[]", "server-data");
179+
let callCount = 0;
180+
const cachedFn = query(async () => {
181+
callCount++;
182+
return "fresh-data";
183+
}, "nativeRestore");
184+
185+
// Restoring where the user has been: the payload is a minute old,
186+
// well within the cache's own retention window.
187+
advanceClock(60 * 1000);
188+
currentIntent = "native";
189+
const result = await cachedFn();
190+
expect(result).toBe("server-data");
191+
expect(callCount).toBe(0);
192+
});
193+
});
194+
195+
test("back/forward past CACHE_TIMEOUT refetches", async () => {
196+
return createRoot(async () => {
197+
seedFlightEntry("nativeStale[]", "stale-server-data");
198+
let callCount = 0;
199+
const cachedFn = query(async () => {
200+
callCount++;
201+
return "fresh-data";
202+
}, "nativeStale");
203+
204+
// Past the retention bar an entry the router had fetched itself
205+
// would already have been swept — the payload gets no more grace.
206+
advanceClock(CACHE_TIMEOUT + 1000);
207+
currentIntent = "native";
208+
const result = await cachedFn();
209+
expect(result).toBe("fresh-data");
210+
expect(callCount).toBe(1);
211+
});
212+
});
213+
214+
test("an adopted entry keeps the payload's age: navigation past the short window refetches", async () => {
215+
return createRoot(async () => {
216+
seedFlightEntry("adoptedThenNavigate[]", "server-data");
217+
let callCount = 0;
218+
const cachedFn = query(async () => {
219+
callCount++;
220+
return "fresh-data";
221+
}, "adoptedThenNavigate");
222+
223+
// Hydration adopts and seeds the cache...
224+
const adopted = await cachedFn();
225+
expect(adopted).toBe("server-data");
226+
expect(callCount).toBe(0);
227+
228+
// ...but adoption must not grant fetched-now freshness: the entry
229+
// is stamped at boot, so a navigation past the short window sees
230+
// the payload's true age and refetches.
231+
advanceClock(PRELOAD_TIMEOUT + 1000);
232+
currentIntent = "navigate";
233+
const result = await cachedFn();
234+
expect(result).toBe("fresh-data");
235+
expect(callCount).toBe(1);
236+
});
237+
});
238+
239+
test("an adopted entry satisfies a navigation inside the short window", async () => {
240+
return createRoot(async () => {
241+
seedFlightEntry("adoptedThenQuickNavigate[]", "server-data");
242+
let callCount = 0;
243+
const cachedFn = query(async () => {
244+
callCount++;
245+
return "fresh-data";
246+
}, "adoptedThenQuickNavigate");
247+
248+
await cachedFn();
249+
expect(callCount).toBe(0);
250+
251+
currentIntent = "navigate";
252+
const result = await cachedFn();
253+
expect(result).toBe("server-data");
254+
expect(callCount).toBe(0);
255+
});
79256
});
80257
});
81258
});

0 commit comments

Comments
 (0)