Skip to content

Commit 518a9e7

Browse files
authored
fix(cache): SWR background revalidation under a derived context — no shared handle-store swap, no shared-arg stamping (#684 plan 010) (#689)
* fix(cache): SWR background revalidation runs under a derived context — no shared handle-store swap, no shared-arg stamping (#684 plan 010) Production waitUntil is Promise.resolve().then(fn), so the stale-hit background revalidation's prologue runs one microtask after scheduling — INSIDE the foreground's render window. The prologue swapped the SHARED requestCtx._handleStore (restore only in finally, i.e. after the whole revalidation's I/O) and stamped INSIDE_CACHE_EXEC onto shared tainted args. Consequences, all reproduced with production-faithful scheduling: (a) foreground handle pushes during the window landed in the background's isolated store — lost from the live document; (b) those misrouted pushes were PERSISTED into the revalidated cache entry (cross-contamination); (c) a concurrent foreground ctx.set()/ctx.headers.*() threw INSIDE_CACHE_EXEC. The existing suite pinned the hazardous behavior behind queue-style waitUntil mocks that run the background after the foreground finished — exactly the ordering production does not have. Fix: the background body runs under a DERIVED context (Object.create(requestCtx) with an own _handleStore — the shell-capture isolation pattern). Background pushes land in the isolated store and are captured/persisted as before; the foreground's store is never touched; no restore step exists because nothing shared is mutated. The background no longer stamps shared args: in-fn misuse is caught by the miss path's stamps on the function's FIRST execution (an entry only becomes stale-revalidatable because a stamped miss ran clean) — that invariant is now recorded at the miss-path stamp itself. Tests: the two pinning tests re-pointed to the safe contract; a new production-faithful race test gates the background open mid-window and asserts no swap, no stamp, foreground push reaches the live store, and the revalidated entry carries only background pushes. The mocked runWithRequestContext now threads its ctx (a passthrough would hide the isolation under test). Red-before-green: 2 failed on the old code, 20/20 with the fix. * ci: trigger full run post-ready
1 parent b7588cb commit 518a9e7

2 files changed

Lines changed: 152 additions & 61 deletions

File tree

‎packages/rangojs-router/src/cache/__tests__/cache-runtime-stale.test.ts‎

Lines changed: 111 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -23,12 +23,22 @@ vi.mock("@vitejs/plugin-rsc/rsc", () => ({
2323

2424
// Mock request context. runWithRequestContext is exercised by the background
2525
// revalidation path (it re-establishes the request-context ALS so the cached
26-
// body's getRequestContext() resolves off the request's I/O context); the mock
27-
// just invokes the callback since getRequestContext is stubbed separately.
26+
// body's getRequestContext() resolves off the request's I/O context). The mock
27+
// THREADS the ctx for the callback's synchronous window: the background body
28+
// must observe the DERIVED context (own isolated _handleStore), not the shared
29+
// foreground one — a passthrough mock would hide the isolation under test.
2830
const mockGetRequestContext = vi.fn<() => any>(() => null);
2931
vi.mock("../../server/request-context.js", () => ({
3032
getRequestContext: () => mockGetRequestContext(),
31-
runWithRequestContext: <T>(_ctx: unknown, fn: () => T): T => fn(),
33+
runWithRequestContext: <T>(ctx: unknown, fn: () => T): T => {
34+
const prev = mockGetRequestContext.getMockImplementation();
35+
mockGetRequestContext.mockImplementation(() => ctx);
36+
try {
37+
return fn();
38+
} finally {
39+
mockGetRequestContext.mockImplementation(prev ?? (() => null));
40+
}
41+
},
3242
}));
3343

3444
// Mock segment codec — identity transforms for testing
@@ -256,7 +266,12 @@ describe("use cache stale revalidation handle preservation", () => {
256266
}
257267
});
258268

259-
it("stamps INSIDE_CACHE_EXEC on tainted args during stale background revalidation", async () => {
269+
it("does NOT stamp INSIDE_CACHE_EXEC on shared tainted args during stale background revalidation", async () => {
270+
// The tainted arg is the live HandlerContext the still-rendering
271+
// foreground holds; a stamp on it makes a concurrent foreground
272+
// ctx.set()/ctx.headers.*() throw for the whole revalidation window
273+
// (issue #684, plan 010). In-fn misuse is caught by the foreground miss
274+
// path's stamps on the function's FIRST execution instead.
260275
const waitUntilFns: Array<() => Promise<void>> = [];
261276

262277
const mockStore = {
@@ -307,17 +322,103 @@ describe("use cache stale revalidation handle preservation", () => {
307322
expect(waitUntilFns).toHaveLength(1);
308323
await waitUntilFns[0]();
309324

310-
// Tainted args should be stamped during background execution
311-
expect(taintedDuringBgExec).toBe(true);
312-
// RequestContext is intentionally NOT stamped in background to avoid
313-
// polluting the shared foreground context (see cache-runtime.ts comment)
325+
// Neither the shared arg nor the request context is stamped in the
326+
// background — both are live foreground objects.
327+
expect(taintedDuringBgExec).toBe(false);
314328
expect(requestCtxTaintedDuringBgExec).toBe(false);
315-
316-
// After background execution, the stamps should be cleaned up
317329
expect((taintedCtx as any)[INSIDE_CACHE_EXEC]).toBeUndefined();
318330
expect((requestCtxObj as any)[INSIDE_CACHE_EXEC]).toBeUndefined();
319331
});
320332

333+
it("background revalidation never mutates the shared context mid-render (production-faithful microtask scheduling)", async () => {
334+
// The unsafe pre-fix shape only stayed green because the queue-style
335+
// waitUntil mocks above run the background AFTER the foreground finished.
336+
// Production waitUntil is Promise.resolve().then(fn)
337+
// (request-context.ts): the background prologue runs one microtask after
338+
// scheduling, INSIDE the foreground's render window. This test uses that
339+
// scheduling and holds the background open on a gate to inspect the
340+
// window. Pre-fix, all four assertions in the window failed: the shared
341+
// _handleStore was swapped, the foreground push landed in the background
342+
// store (lost from the live document), it was persisted into the
343+
// revalidated entry, and the shared arg carried INSIDE_CACHE_EXEC.
344+
const backgroundTasks: Array<Promise<void>> = [];
345+
346+
const mockStore = {
347+
getItem: vi.fn(),
348+
setItem: vi.fn().mockResolvedValue(undefined),
349+
};
350+
351+
const liveHandleStore = {
352+
push: vi.fn(),
353+
settled: Promise.resolve(),
354+
getDataForSegment: vi.fn().mockReturnValue({}),
355+
};
356+
357+
const taintedCtx = makeTaintedCtx();
358+
359+
const requestCtxObj: any = {
360+
_cacheStore: mockStore,
361+
_cacheProfiles: { default: { ttl: 60, swr: 120 } },
362+
_handleStore: liveHandleStore,
363+
waitUntil: (fn: () => Promise<void>) => {
364+
backgroundTasks.push(Promise.resolve().then(fn));
365+
},
366+
};
367+
mockGetRequestContext.mockReturnValue(requestCtxObj);
368+
369+
mockStore.getItem.mockResolvedValueOnce({
370+
value: JSON.stringify("stale-result"),
371+
handles: {},
372+
shouldRevalidate: true,
373+
});
374+
375+
// Gate the background body open so the overlap window can be inspected.
376+
let releaseGate!: () => void;
377+
const gate = new Promise<void>((resolve) => {
378+
releaseGate = resolve;
379+
});
380+
const fn = async (_ctx: any) => {
381+
// Push via the AMBIENT context, the way loader/handle plumbing reads
382+
// the store (static-store.ts / loader-resolution.ts) — must resolve to
383+
// the ISOLATED background store, never the live one.
384+
mockGetRequestContext()._handleStore.push("test#H", "seg-bg", "bg-value");
385+
await gate;
386+
return "fresh-result";
387+
};
388+
389+
const cached = registerCachedFunction(fn, "test-race-window", "default");
390+
await expect(cached(taintedCtx)).resolves.toBe("stale-result");
391+
392+
// Let the background prologue run (one microtask), then inspect the
393+
// window while the body is still gated open — this is the foreground
394+
// mid-render state.
395+
await Promise.resolve();
396+
await Promise.resolve();
397+
const INSIDE_CACHE_EXEC = Symbol.for("rango:inside-cache-exec");
398+
expect(requestCtxObj._handleStore).toBe(liveHandleStore);
399+
expect((taintedCtx as any)[INSIDE_CACHE_EXEC]).toBeUndefined();
400+
401+
// A foreground handle push inside the window reaches the LIVE store.
402+
requestCtxObj._handleStore.push("test#H", "seg-fg", "fg-value");
403+
expect(liveHandleStore.push).toHaveBeenCalledWith(
404+
"test#H",
405+
"seg-fg",
406+
"fg-value",
407+
);
408+
409+
releaseGate();
410+
await Promise.all(backgroundTasks);
411+
412+
// The revalidated entry carries the background's push, not the
413+
// foreground's (no cross-contamination).
414+
expect(mockStore.setItem).toHaveBeenCalledTimes(1);
415+
const persistedHandles = String(
416+
mockStore.setItem.mock.calls[0]![2].handles,
417+
);
418+
expect(persistedHandles).toContain("bg-value");
419+
expect(persistedHandles).not.toContain("fg-value");
420+
});
421+
321422
it("fresh hit path does not trigger background revalidation", async () => {
322423
const waitUntilFns: Array<() => Promise<void>> = [];
323424

‎packages/rangojs-router/src/cache/cache-runtime.ts‎

Lines changed: 41 additions & 51 deletions
Original file line numberDiff line numberDiff line change
@@ -412,26 +412,26 @@ export function registerCachedFunction<T extends (...args: any[]) => any>(
412412
try {
413413
const result = await serveCached(cached);
414414
// Background revalidation — must capture handles if tainted args present.
415-
// Use an isolated handle store so background pushes don't pollute the
416-
// live response or throw LateHandlePushError on the completed store.
417-
// Same isolation pattern as route-level background-revalidation.ts.
418415
runBackground(requestCtx, async () => {
419-
// The closure-captured requestCtx is reused for the framework's own
420-
// reads (handle store swap, error reporting) AND, below, to
421-
// re-establish the request-context ALS around the user fn. ALS context
422-
// may be gone inside waitUntil: on workerd a waitUntil task runs
423-
// detached from the request's I/O context, so getRequestContext()
424-
// inside the cached body would otherwise throw.
425-
let originalHandleStore:
426-
| ReturnType<typeof createHandleStore>
427-
| undefined;
428-
if (hasTaintedArgs && requestCtx) {
429-
originalHandleStore = requestCtx._handleStore;
430-
requestCtx._handleStore = createHandleStore();
431-
}
432-
const bgHandleStore = hasTaintedArgs
433-
? requestCtx?._handleStore
434-
: undefined;
416+
// The background body runs under a DERIVED context with an OWN
417+
// _handleStore (the shell-capture isolation pattern —
418+
// shell-capture.ts attemptCapture): its handle pushes land in the
419+
// isolated store (captured below, persisted with the entry) while
420+
// the foreground keeps pushing into the ORIGINAL store, untouched.
421+
// Derivation matters because the foreground is STILL RENDERING here
422+
// — runBackground/waitUntil starts the task on the next microtask,
423+
// not after the response. The previous shape swapped
424+
// requestCtx._handleStore in place (restore in finally), which
425+
// routed the whole overlap window's foreground pushes into the
426+
// background store: lost from the live document AND persisted into
427+
// the revalidated entry (issue #684, plan 010).
428+
const bgHandleStore =
429+
hasTaintedArgs && requestCtx ? createHandleStore() : undefined;
430+
const bgCtx: typeof requestCtx = bgHandleStore
431+
? Object.assign(Object.create(requestCtx), {
432+
_handleStore: bgHandleStore,
433+
})
434+
: requestCtx;
435435
let bgCapture: HandleCapture | undefined;
436436
let bgStopCapture: (() => void) | undefined;
437437
if (bgHandleStore) {
@@ -440,37 +440,26 @@ export function registerCachedFunction<T extends (...args: any[]) => any>(
440440
bgStopCapture = c.stop;
441441
}
442442

443-
// Stamp tainted ARGS only — not requestCtx. The args stamp guards
444-
// direct ctx method calls (ctx.set, ctx.header, ctx.onResponse, etc.)
445-
// which is sufficient for correctness.
446-
//
447-
// We intentionally skip stamping requestCtx here because:
448-
// 1. runBackground starts the async task synchronously (before the
449-
// first await), so stampCacheExec would pollute the shared
450-
// requestCtx while the foreground pipeline is still running.
451-
// This causes assertNotInsideCacheExec to fire when cache-store
452-
// later calls requestCtx.onResponse().
453-
// 2. requestCtx methods are closure-bound to the original ctx, so
454-
// neither Object.create() nor a proxy can isolate the stamp.
455-
// 3. The foreground miss path already stamps requestCtx and catches
456-
// cookies()/headers() misuse on first execution. The background
457-
// re-runs the same function with the same request.
458-
const bgTaintedArgs: unknown[] = [];
459-
for (const arg of args) {
460-
if (isTainted(arg)) {
461-
stampCacheExec(arg as object);
462-
bgTaintedArgs.push(arg);
463-
}
464-
}
443+
// Tainted args are NOT stamped here, in contrast to the foreground
444+
// miss path below. The args include the live HandlerContext the
445+
// still-rendering foreground holds, and INSIDE_CACHE_EXEC is a
446+
// property stamped onto that SHARED object — so for the whole
447+
// revalidation window a concurrent foreground ctx.set() /
448+
// ctx.headers.*() would throw (issue #684, plan 010). requestCtx is
449+
// not stamped for the same reason. In-fn misuse is already caught
450+
// by the miss path's stamps on the function's FIRST execution — the
451+
// background re-runs the same function with the same request.
465452

466453
try {
467454
// Re-establish the request-context ALS so a "use cache" body that
468455
// reads the ambient getRequestContext() (e.g.
469456
// getRequestContext().env.ApiKey) resolves during the background
470457
// revalidation instead of throwing "called outside of a request
471458
// context". runWithRequestContext sets the store for fn's
472-
// synchronous kickoff; its async continuations inherit it.
473-
const scoped = runWithRequestContext(requestCtx, () =>
459+
// synchronous kickoff; its async continuations inherit it. The
460+
// DERIVED context goes in, so ambient _handleStore reads inside
461+
// the body resolve to the isolated store.
462+
const scoped = runWithRequestContext(bgCtx, () =>
474463
runWithCacheTagScope(() => fn.apply(this, args)),
475464
);
476465
const freshResult = await scoped.result;
@@ -507,15 +496,9 @@ export function registerCachedFunction<T extends (...args: any[]) => any>(
507496
"[use cache] background revalidation failed",
508497
requestCtx,
509498
);
510-
} finally {
511-
for (const arg of bgTaintedArgs) {
512-
unstampCacheExec(arg as object);
513-
}
514-
// Restore original handle store
515-
if (originalHandleStore && requestCtx) {
516-
requestCtx._handleStore = originalHandleStore;
517-
}
518499
}
500+
// No finally: nothing shared was mutated — the derived context and
501+
// its handle store are garbage after the task settles.
519502
});
520503
return result;
521504
} catch (error) {
@@ -601,6 +584,13 @@ export function registerCachedFunction<T extends (...args: any[]) => any>(
601584
// inside the cached function body (those side effects are lost on hit).
602585
// Uses ref-counted stamp/unstamp so overlapping executions
603586
// sharing the same ctx don't clear each other's guards.
587+
//
588+
// LOAD-BEARING for the stale-revalidation path above: the background
589+
// re-execution deliberately does NOT re-stamp (the objects are live
590+
// foreground state mid-render), relying on THIS stamp having caught in-fn
591+
// misuse on the function's first execution — an entry only becomes
592+
// stale-revalidatable because a stamped miss ran clean and stored it. Do
593+
// not create a "use cache" entry via any path that skips this stamp.
604594
const taintedArgs: unknown[] = [];
605595
for (const arg of args) {
606596
if (isTainted(arg)) {

0 commit comments

Comments
 (0)