Skip to content

Commit 849f96b

Browse files
authored
refactor(router): matrix-critical de-duplications — middleware merge, loader-cache interceptor, cache-hit loaders, parallel-slot (#568) (#576)
* refactor(router): extract middleware merge-and-clone Response builder (#568) Replace 3 near-identical merge-and-clone Response sites in executeMiddleware (end-of-chain next() and short-circuit) and executeInterceptMiddleware with a private mergeResponse(base, stub, {stubOverridesNonCookie, mergeReqCtx}) helper. The two flags encode the only real differences: stubOverridesNonCookie (chain ran vs explicit short-circuit) and mergeReqCtx (false ONLY for the intercept path -- the one deliberate divergence, pinned by intercept-middleware-headers). WebSocket-upgrade early returns + the hasStubHeaders gate stay at the call sites. Behavior-preserving; semantic matrix + middleware e2e green. * refactor(router): extract shared cache-hit fresh-loader resolution (#568) yieldFromStore (prerender-store path) and withCacheLookup (runtime cache-hit path) duplicated the fresh-loader-on-cache-hit block verbatim (loaders are never cached): the isFullMatch branch, resolveLoadersOnly[WithRevalidation] calls, state.matchedIds update, and the loader-resolve + cache-hit metrics. Extract resolveFreshLoadersAndYield(). The router resolve fns are passed in (captured early by each caller) rather than re-read from the ALS-backed getRouterContext() inside the helper, preserving workerd ALS-disruption robustness. The render barrier + cacheSource assignment stay at each call site (they differ). Behavior- preserving; semantic matrix + cache e2e (dev+prod) green. * refactor(router): replace loader-cache ctx.use chain with a stable interceptor (#568) resolveLoaderData rebound ctx.use once per cached loader, chaining one wrapper per loader (O(N) dispatch) and relying on an undocumented synchronous capture-before-overwrite invariant. Install ONE stable interceptor on the first cached loader that consults a per-ctx override table (_loaderCacheOverrides); each subsequent cached loader just primes the table (O(1) dispatch). The cache-miss execute runs through the captured pre-interceptor ctx.use (_loaderCacheOriginalUse), so a loader never awaits its own in-flight promise. Stays agnostic to which setup mode installed ctx.use (loader/silent/build), like the old rebind. Adds a multi-cached-loader accumulation test. Behavior- preserving; matrix + loader-cache unit + cache e2e green. * refactor(router): extract parallel-slot component resolution (#568) resolveParallelSegmentsWithRevalidation and the orphan-inlined loop in resolveOrphanLayoutWithRevalidation duplicated the parallel-slot component-resolution block (~45 lines): tryStaticSlot, then run the slot handler with the _currentSegmentId slot-id pin, handlerRan flag, and streamed-handler wrap. Extract resolveParallelSlotComponent() returning {component, handlerRan}. The block is byte-identical between the two and SEPARABLE from their known divergences: the defaultOverride/shouldResolve seed is computed by the caller before the call, and loader-resolution ordering stays at the call site (orphan before push, main after) -- neither is touched. Behavior-preserving; semantic matrix + parallel-revalidate-fns + parallel-reval e2e green.
1 parent dce9296 commit 849f96b

6 files changed

Lines changed: 323 additions & 255 deletions

File tree

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

Lines changed: 37 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -646,5 +646,42 @@ describe("loader-cache", () => {
646646
const result = await ctx.use(loader2);
647647
expect(result).toEqual({ other: true });
648648
});
649+
650+
it("accumulates multiple cached loaders behind one stable interceptor (no O(N) chain)", async () => {
651+
const loaderA = createMockLoader("loader-a", { data: "A" });
652+
const loaderB = createMockLoader("loader-b", { data: "B" });
653+
const loaderC = createMockLoader("loader-c", { data: "C" }); // not cached
654+
const entryA = createLoaderEntry(loaderA, { store: createMockStore() });
655+
const entryB = createLoaderEntry(loaderB, { store: createMockStore() });
656+
const ctx = createMockCtx();
657+
const originalUse = ctx.use;
658+
659+
const pA = resolveLoaderData(entryA, ctx, "/a");
660+
const interceptorAfterA = ctx.use;
661+
const pB = resolveLoaderData(entryB, ctx, "/b");
662+
663+
// The interceptor is installed exactly ONCE: the 2nd cached loader primes
664+
// the override table, it does NOT re-wrap ctx.use (the old O(N) chain).
665+
expect(ctx.use).not.toBe(originalUse);
666+
expect(ctx.use).toBe(interceptorAfterA);
667+
668+
await Promise.all([pA, pB]);
669+
// Each loader executed exactly once (cache miss -> captured originalUse).
670+
expect(loaderA).toHaveBeenCalledTimes(1);
671+
expect(loaderB).toHaveBeenCalledTimes(1);
672+
673+
// A handler awaiting either loader gets ITS OWN memoized promise (the
674+
// override), never the other's, and never a re-execution.
675+
expect(ctx.use(loaderA)).toBe(pA);
676+
expect(ctx.use(loaderB)).toBe(pB);
677+
await expect(ctx.use(loaderA)).resolves.toEqual({ data: "A" });
678+
await expect(ctx.use(loaderB)).resolves.toEqual({ data: "B" });
679+
expect(loaderA).toHaveBeenCalledTimes(1);
680+
expect(loaderB).toHaveBeenCalledTimes(1);
681+
682+
// A non-cached loader still passes through to the original ctx.use.
683+
await expect(ctx.use(loaderC)).resolves.toEqual({ data: "C" });
684+
expect(loaderC).toHaveBeenCalledTimes(1);
685+
});
649686
});
650687
});

‎packages/rangojs-router/src/router/match-middleware/cache-lookup.ts‎

Lines changed: 95 additions & 125 deletions
Original file line numberDiff line numberDiff line change
@@ -93,7 +93,7 @@
9393
*/
9494
import type { ResolvedSegment } from "../../types.js";
9595
import type { MatchContext, MatchPipelineState } from "../match-context.js";
96-
import { getRouterContext } from "../router-context.js";
96+
import { getRouterContext, type RouterContext } from "../router-context.js";
9797
import { resolveSink, safeEmit } from "../telemetry.js";
9898
import { pushRevalidationTraceEntry, isTraceActive } from "../logging.js";
9999
import { treeHasStreaming } from "./segment-resolution.js";
@@ -150,6 +150,81 @@ async function ensurePrerenderDeps() {
150150
* Deserializes segments, replays handle data, yields segments with partial
151151
* navigation nullification, and resolves fresh loaders.
152152
*/
153+
// Resolve loaders fresh on a cache hit (loaders are NEVER cached) and yield
154+
// the loader segments, updating state.matchedIds and pushing the loader-resolve
155+
// + cache-hit metrics. Shared verbatim by the prerender-store path
156+
// (yieldFromStore) and the runtime cache-hit path (withCacheLookup). The router
157+
// resolve fns are passed in (captured early by the callers) rather than re-read
158+
// from getRouterContext() here, because that is ALS-backed and the callers run
159+
// awaits before reaching this point (workerd can disrupt ALS mid-pipeline).
160+
async function* resolveFreshLoadersAndYield<TEnv>(
161+
ctx: MatchContext<TEnv>,
162+
state: MatchPipelineState,
163+
pipelineStart: number,
164+
ms: MatchContext<TEnv>["metricsStore"],
165+
resolveLoadersOnly: RouterContext<TEnv>["resolveLoadersOnly"],
166+
resolveLoadersOnlyWithRevalidation: RouterContext<TEnv>["resolveLoadersOnlyWithRevalidation"],
167+
): AsyncGenerator<ResolvedSegment> {
168+
const loaderStart = performance.now();
169+
170+
if (ctx.isFullMatch) {
171+
if (resolveLoadersOnly) {
172+
const loaderSegments = await ctx.Store.run(() =>
173+
resolveLoadersOnly(ctx.entries, ctx.handlerContext),
174+
);
175+
state.matchedIds = state.cachedMatchedIds!;
176+
for (const segment of loaderSegments) {
177+
yield segment;
178+
}
179+
} else {
180+
state.matchedIds = state.cachedMatchedIds!;
181+
}
182+
} else {
183+
if (resolveLoadersOnlyWithRevalidation) {
184+
const loaderResult = await ctx.Store.run(() =>
185+
resolveLoadersOnlyWithRevalidation(
186+
ctx.entries,
187+
ctx.handlerContext,
188+
ctx.clientSegmentSet,
189+
ctx.prevParams,
190+
ctx.request,
191+
ctx.prevUrl,
192+
ctx.url,
193+
ctx.routeKey,
194+
ctx.actionContext,
195+
// Loaders are never cached in the segment cache, so segment staleness
196+
// must not propagate; browser-sent staleness (ctx.stale) still must.
197+
ctx.stale || undefined,
198+
),
199+
);
200+
state.matchedIds = [
201+
...state.cachedMatchedIds!,
202+
...loaderResult.matchedIds,
203+
];
204+
for (const segment of loaderResult.segments) {
205+
yield segment;
206+
}
207+
} else {
208+
state.matchedIds = state.cachedMatchedIds!;
209+
}
210+
}
211+
212+
if (ms) {
213+
const loaderEnd = performance.now();
214+
ms.metrics.push({
215+
label: "pipeline:loader-resolve",
216+
duration: loaderEnd - loaderStart,
217+
startTime: loaderStart - ms.requestStart,
218+
depth: 1,
219+
});
220+
ms.metrics.push({
221+
label: "pipeline:cache-hit",
222+
duration: loaderEnd - pipelineStart,
223+
startTime: pipelineStart - ms.requestStart,
224+
});
225+
}
226+
}
227+
153228
async function* yieldFromStore<TEnv>(
154229
entry: PrerenderEntry,
155230
ctx: MatchContext<TEnv>,
@@ -216,64 +291,15 @@ async function* yieldFromStore<TEnv>(
216291
yield segment;
217292
}
218293

219-
// Resolve loaders fresh (loaders are never pre-rendered/cached)
220-
const ms = ctx.metricsStore;
221-
const loaderStart = performance.now();
222-
223-
if (ctx.isFullMatch) {
224-
if (resolveLoadersOnly) {
225-
const loaderSegments = await ctx.Store.run(() =>
226-
resolveLoadersOnly(ctx.entries, ctx.handlerContext),
227-
);
228-
state.matchedIds = state.cachedMatchedIds!;
229-
for (const segment of loaderSegments) {
230-
yield segment;
231-
}
232-
} else {
233-
state.matchedIds = state.cachedMatchedIds!;
234-
}
235-
} else {
236-
if (resolveLoadersOnlyWithRevalidation) {
237-
const loaderResult = await ctx.Store.run(() =>
238-
resolveLoadersOnlyWithRevalidation(
239-
ctx.entries,
240-
ctx.handlerContext,
241-
ctx.clientSegmentSet,
242-
ctx.prevParams,
243-
ctx.request,
244-
ctx.prevUrl,
245-
ctx.url,
246-
ctx.routeKey,
247-
ctx.actionContext,
248-
ctx.stale || undefined,
249-
),
250-
);
251-
state.matchedIds = [
252-
...state.cachedMatchedIds!,
253-
...loaderResult.matchedIds,
254-
];
255-
for (const segment of loaderResult.segments) {
256-
yield segment;
257-
}
258-
} else {
259-
state.matchedIds = state.cachedMatchedIds!;
260-
}
261-
}
262-
263-
if (ms) {
264-
const loaderEnd = performance.now();
265-
ms.metrics.push({
266-
label: "pipeline:loader-resolve",
267-
duration: loaderEnd - loaderStart,
268-
startTime: loaderStart - ms.requestStart,
269-
depth: 1,
270-
});
271-
ms.metrics.push({
272-
label: "pipeline:cache-hit",
273-
duration: loaderEnd - pipelineStart,
274-
startTime: pipelineStart - ms.requestStart,
275-
});
276-
}
294+
// Resolve loaders fresh (loaders are never pre-rendered/cached).
295+
yield* resolveFreshLoadersAndYield(
296+
ctx,
297+
state,
298+
pipelineStart,
299+
ctx.metricsStore,
300+
resolveLoadersOnly,
301+
resolveLoadersOnlyWithRevalidation,
302+
);
277303
}
278304

279305
/**
@@ -550,71 +576,15 @@ export function withCacheLookup<TEnv>(
550576
barrierReqCtx._resolveRenderBarrier(cacheResult.segments);
551577
}
552578

553-
const Store = ctx.Store;
554-
const loaderStart = performance.now();
555-
556-
if (ctx.isFullMatch) {
557-
if (resolveLoadersOnly) {
558-
const loaderSegments = await Store.run(() =>
559-
resolveLoadersOnly(ctx.entries, ctx.handlerContext),
560-
);
561-
562-
state.matchedIds = state.cachedMatchedIds!;
563-
564-
for (const segment of loaderSegments) {
565-
yield segment;
566-
}
567-
} else {
568-
state.matchedIds = state.cachedMatchedIds!;
569-
}
570-
} else {
571-
if (resolveLoadersOnlyWithRevalidation) {
572-
const loaderResult = await Store.run(() =>
573-
resolveLoadersOnlyWithRevalidation(
574-
ctx.entries,
575-
ctx.handlerContext,
576-
ctx.clientSegmentSet,
577-
ctx.prevParams,
578-
ctx.request,
579-
ctx.prevUrl,
580-
ctx.url,
581-
ctx.routeKey,
582-
ctx.actionContext,
583-
// Loaders are never cached in the segment cache, so segment
584-
// staleness (cacheResult.shouldRevalidate) must not propagate.
585-
// But browser-sent staleness (ctx.stale) — indicating an action
586-
// happened in this or another tab — must still reach loaders.
587-
ctx.stale || undefined,
588-
),
589-
);
590-
591-
// Update state with fresh loader matchedIds
592-
state.matchedIds = [
593-
...state.cachedMatchedIds!,
594-
...loaderResult.matchedIds,
595-
];
596-
597-
// Yield fresh loader segments
598-
for (const segment of loaderResult.segments) {
599-
yield segment;
600-
}
601-
} else {
602-
state.matchedIds = state.cachedMatchedIds!;
603-
}
604-
}
605-
if (ms) {
606-
const loaderEnd = performance.now();
607-
ms.metrics.push({
608-
label: "pipeline:loader-resolve",
609-
duration: loaderEnd - loaderStart,
610-
startTime: loaderStart - ms.requestStart,
611-
depth: 1,
612-
});
613-
ms.metrics.push({
614-
label: "pipeline:cache-hit",
615-
duration: loaderEnd - pipelineStart,
616-
startTime: pipelineStart - ms.requestStart,
617-
});
618-
}
579+
// Resolve loaders fresh (loaders are never cached). Shared with the
580+
// prerender-store path via resolveFreshLoadersAndYield.
581+
yield* resolveFreshLoadersAndYield(
582+
ctx,
583+
state,
584+
pipelineStart,
585+
ms,
586+
resolveLoadersOnly,
587+
resolveLoadersOnlyWithRevalidation,
588+
);
619589
};
620590
}

‎packages/rangojs-router/src/router/middleware.ts‎

Lines changed: 40 additions & 25 deletions
Original file line numberDiff line numberDiff line change
@@ -326,6 +326,29 @@ function mergeReqCtxStub(
326326
});
327327
}
328328

329+
// Clone `base` with stub headers merged into a fresh Headers (the clone keeps
330+
// the body mutable for post-next() modifications). Set-Cookie is always
331+
// appended; other headers obey stubOverridesNonCookie (see mergeStubHeaders).
332+
// mergeReqCtx folds in RequestContext stub cookies/headers; the intercept
333+
// short-circuit path passes false (its reqCtx headers are not merged here),
334+
// which is the one deliberate divergence between the call sites.
335+
function mergeResponse(
336+
base: Response,
337+
stub: Headers,
338+
opts: { stubOverridesNonCookie: boolean; mergeReqCtx: boolean },
339+
): Response {
340+
const mergedHeaders = new Headers(base.headers);
341+
mergeStubHeaders(mergedHeaders, stub, opts.stubOverridesNonCookie);
342+
if (opts.mergeReqCtx) {
343+
mergeReqCtxStub(mergedHeaders, _getRequestContext());
344+
}
345+
return new Response(base.body, {
346+
status: base.status,
347+
statusText: base.statusText,
348+
headers: mergedHeaders,
349+
});
350+
}
351+
329352
/**
330353
* Execute middleware chain
331354
*
@@ -364,20 +387,16 @@ export async function executeMiddleware<TEnv>(
364387
// End of chain - call actual RSC handler
365388
const response = await finalHandler();
366389

367-
const mergedHeaders = new Headers(response.headers);
368-
mergeStubHeaders(mergedHeaders, stubResponse.headers, true);
369-
mergeReqCtxStub(mergedHeaders, _getRequestContext());
370-
371390
if (isWebSocketUpgradeResponse(response)) {
372391
responseHolder.response = response;
373392
return response;
374393
}
375394

376-
// Clone response with merged headers (mutable for post-next() modifications)
377-
responseHolder.response = new Response(response.body, {
378-
status: response.status,
379-
statusText: response.statusText,
380-
headers: mergedHeaders,
395+
// Chain ran to completion: stub headers overwrite (stubOverridesNonCookie)
396+
// and reqCtx stub headers are merged in.
397+
responseHolder.response = mergeResponse(response, stubResponse.headers, {
398+
stubOverridesNonCookie: true,
399+
mergeReqCtx: true,
381400
});
382401

383402
return responseHolder.response;
@@ -476,13 +495,11 @@ export async function executeMiddleware<TEnv>(
476495
responseHolder.response = result;
477496
return result;
478497
}
479-
const mergedHeaders = new Headers(result.headers);
480-
mergeStubHeaders(mergedHeaders, stubResponse.headers, false);
481-
mergeReqCtxStub(mergedHeaders, _getRequestContext());
482-
const merged = new Response(result.body, {
483-
status: result.status,
484-
statusText: result.statusText,
485-
headers: mergedHeaders,
498+
// Explicit short-circuit: the returned Response's own headers win
499+
// (stubOverridesNonCookie=false); reqCtx stub headers still merge in.
500+
const merged = mergeResponse(result, stubResponse.headers, {
501+
stubOverridesNonCookie: false,
502+
mergeReqCtx: true,
486503
});
487504
responseHolder.response = merged;
488505
return merged;
@@ -637,15 +654,13 @@ export async function executeInterceptMiddleware<TEnv>(
637654
});
638655

639656
if (hasStubHeaders) {
640-
// Clone and merge headers from stub into early response.
641-
// Only fill in missing headers — the returned Response's explicit
642-
// headers take precedence, matching executeMiddleware behavior.
643-
const mergedHeaders = new Headers(response.headers);
644-
mergeStubHeaders(mergedHeaders, stubResponse.headers, false);
645-
return new Response(response.body, {
646-
status: response.status,
647-
statusText: response.statusText,
648-
headers: mergedHeaders,
657+
// Only fill in missing headers — the returned Response's explicit headers
658+
// take precedence (stubOverridesNonCookie=false), matching executeMiddleware.
659+
// mergeReqCtx=false: the intercept path deliberately does NOT merge reqCtx
660+
// stub headers here (pinned by intercept-middleware-headers.test.ts).
661+
return mergeResponse(response, stubResponse.headers, {
662+
stubOverridesNonCookie: false,
663+
mergeReqCtx: false,
649664
});
650665
}
651666
return response;

0 commit comments

Comments
 (0)