@decocms/blocks 7.86.5 → 7.87.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@decocms/blocks",
3
- "version": "7.86.5",
3
+ "version": "7.87.0",
4
4
  "type": "module",
5
5
  "engines": {
6
6
  "node": ">=24"
@@ -59,6 +59,7 @@
59
59
  "./sdk/env": "./src/sdk/env.ts",
60
60
  "./sdk/fetchCache": "./src/sdk/fetchCache.ts",
61
61
  "./sdk/fetchTimeout": "./src/sdk/fetchTimeout.ts",
62
+ "./sdk/inflightTimeout": "./src/sdk/inflightTimeout.ts",
62
63
  "./sdk/experiments": "./src/sdk/experiments.ts",
63
64
  "./sdk/flags": "./src/sdk/flags.ts",
64
65
  "./sdk/http": "./src/sdk/http.ts",
@@ -115,7 +116,7 @@
115
116
  "devDependencies": {
116
117
  "@types/react": "^19.0.0",
117
118
  "@types/react-dom": "^19.0.0",
118
- "esbuild": "^0.27.3",
119
+ "esbuild": "^0.28.2",
119
120
  "knip": "^5.86.0",
120
121
  "typescript": "^5.9.0"
121
122
  },
@@ -0,0 +1,138 @@
1
+ /**
2
+ * Cancelled-owner regression for the module-level single-flight maps in
3
+ * sectionLoaders.ts (`layoutInflight`, `sectionLoaderInflight`) and resolve.ts
4
+ * (`resolvedLayoutInflight`).
5
+ *
6
+ * On Workers, when the client of the request that OWNS a shared flight
7
+ * disconnects, the runtime cancels that request's I/O and timers — including
8
+ * the owner's `withInflightTimeout`. The flight never settles and every later
9
+ * request for the same key used to hang for the life of the isolate (CPU ~0,
10
+ * wall 100s → 524). Simulated here: the owner's work never settles and
11
+ * `withInflightTimeout` is a pass-through (its timer "died" with the owner).
12
+ * Joiners must recover on their own timer.
13
+ */
14
+ import { afterEach, describe, expect, it, vi } from "vitest";
15
+
16
+ vi.mock("../sdk/inflightTimeout", async (importActual) => ({
17
+ ...(await importActual<typeof import("../sdk/inflightTimeout")>()),
18
+ withInflightTimeout: <T>(work: Promise<T>) => work,
19
+ }));
20
+
21
+ import { bindCacheStorage } from "../sdk/cacheStorage";
22
+ import { RequestContext } from "../sdk/requestContext";
23
+ import {
24
+ registerCacheableSections,
25
+ registerLayoutSections,
26
+ registerSectionLoader,
27
+ registerSections,
28
+ resolveDecoPage,
29
+ runSingleSectionLoader,
30
+ setBlocks,
31
+ unregisterLayoutSections,
32
+ } from "./index";
33
+ import type { ResolvedSection } from "./resolve";
34
+
35
+ const section = (component: string, index: number): ResolvedSection =>
36
+ ({ component, props: {}, key: `${component}-${index}`, index }) as ResolvedSection;
37
+
38
+ /** First call never settles (owner's request was cancelled); later calls resolve. */
39
+ function deadThenAlive() {
40
+ let calls = 0;
41
+ const loader = vi.fn(async (props: Record<string, unknown>) => {
42
+ calls++;
43
+ if (calls === 1) return new Promise<Record<string, unknown>>(() => {});
44
+ return { ...props, run: calls };
45
+ });
46
+ return loader;
47
+ }
48
+
49
+ afterEach(() => {
50
+ vi.useRealTimers();
51
+ });
52
+
53
+ describe("single-flight joiners of a cancelled owner do not hang", () => {
54
+ it("layout section: joiners rerun after their own timer and keep their own index", async () => {
55
+ vi.useFakeTimers();
56
+ const TYPE = "site/sections/CancelHeader.tsx";
57
+ const loader = deadThenAlive();
58
+ registerSectionLoader(TYPE, loader);
59
+ registerLayoutSections([TYPE]);
60
+ const request = new Request("https://store.com/p");
61
+ try {
62
+ void runSingleSectionLoader(section(TYPE, 0), request);
63
+ const joiners = [1, 2, 3, 4, 5].map((i) => runSingleSectionLoader(section(TYPE, i), request));
64
+ await vi.advanceTimersByTimeAsync(10_000);
65
+ const results = await Promise.all(joiners);
66
+
67
+ expect(results.map((r) => r.index)).toEqual([1, 2, 3, 4, 5]);
68
+ expect(results.every((r) => (r.props as { run?: number }).run === 2)).toBe(true);
69
+ expect(loader).toHaveBeenCalledTimes(2);
70
+ } finally {
71
+ unregisterLayoutSections([TYPE]);
72
+ }
73
+ });
74
+
75
+ it("cacheable section: joiners rerun after their own timer instead of hanging", async () => {
76
+ vi.useFakeTimers();
77
+ const TYPE = "site/sections/CancelShelf.tsx";
78
+ const loader = deadThenAlive();
79
+ registerSectionLoader(TYPE, loader);
80
+ registerCacheableSections({ [TYPE]: { maxAge: 60_000 } });
81
+ const request = new Request("https://store.com/p");
82
+
83
+ void runSingleSectionLoader(section(TYPE, 0), request);
84
+ const joiners = [1, 2, 3].map((i) => runSingleSectionLoader(section(TYPE, i), request));
85
+ await vi.advanceTimersByTimeAsync(10_000);
86
+ const results = await Promise.all(joiners);
87
+
88
+ expect(results.every((r) => (r.props as { run?: number }).run === 2)).toBe(true);
89
+ expect(loader).toHaveBeenCalledTimes(2);
90
+ });
91
+
92
+ it("resolved layout (Header/Footer in resolveDecoPage): a page joining a dead flight still resolves", async () => {
93
+ vi.useFakeTimers();
94
+ const FOOTER = "site/sections/CancelFooter.tsx";
95
+ let imports = 0;
96
+ registerSections({
97
+ [FOOTER]: () => {
98
+ imports++;
99
+ return imports === 1 ? new Promise(() => {}) : Promise.resolve({ default: () => null });
100
+ },
101
+ });
102
+ registerLayoutSections([FOOTER]);
103
+ setBlocks({
104
+ "pages-cancel-a": { path: "/cancel-a", sections: [{ __resolveType: FOOTER }] },
105
+ "pages-cancel-b": { path: "/cancel-b", sections: [{ __resolveType: FOOTER }] },
106
+ });
107
+ try {
108
+ void resolveDecoPage("/cancel-a");
109
+ await vi.advanceTimersByTimeAsync(0);
110
+ const joiner = resolveDecoPage("/cancel-b");
111
+ await vi.advanceTimersByTimeAsync(10_000);
112
+ const page = await joiner;
113
+
114
+ expect(page?.resolvedSections.some((s) => s.component === FOOTER)).toBe(true);
115
+ expect(imports).toBeGreaterThanOrEqual(2);
116
+ } finally {
117
+ unregisterLayoutSections([FOOTER]);
118
+ }
119
+ });
120
+
121
+ it("the owner's shared work is handed to ctx.waitUntil so a client disconnect does not kill it", async () => {
122
+ const TYPE = "site/sections/WaitUntilHeader.tsx";
123
+ registerSectionLoader(TYPE, async (p: Record<string, unknown>) => p);
124
+ registerLayoutSections([TYPE]);
125
+ const request = new Request("https://store.com/p");
126
+ const waitUntil = vi.fn();
127
+ try {
128
+ await RequestContext.run(request, async () => {
129
+ bindCacheStorage({ storage: null, scope: "test", waitUntil });
130
+ await runSingleSectionLoader(section(TYPE, 0), request);
131
+ });
132
+ expect(waitUntil).toHaveBeenCalled();
133
+ expect(waitUntil.mock.calls[0][0]).toBeInstanceOf(Promise);
134
+ } finally {
135
+ unregisterLayoutSections([TYPE]);
136
+ }
137
+ });
138
+ });
@@ -1,11 +1,11 @@
1
1
  import { getMatchersOverride, getRuleOverrideId, hasMatchersOverride } from "../matchers/override";
2
2
  import { getMeter, MetricNames, withTracing } from "../middleware/observability";
3
- import { createCacheStore } from "../sdk/cacheStorage";
3
+ import { cacheBackground, createCacheStore } from "../sdk/cacheStorage";
4
4
  import { detectDevice } from "../sdk/detectDevice";
5
5
  import { djb2Hex } from "../sdk/djb2";
6
6
  import { stickyDecide } from "../sdk/experiments";
7
7
  import { parseSegmentCookie, SEGMENT_COOKIE, type StoredFlag, trafficToPct } from "../sdk/flags";
8
- import { withInflightTimeout } from "../sdk/inflightTimeout";
8
+ import { joinInflight, withInflightTimeout } from "../sdk/inflightTimeout";
9
9
  import { normalizeUrlsInObject } from "../sdk/normalizeUrls";
10
10
  import { stripTrackingParams } from "../sdk/urlUtils";
11
11
  import {
@@ -1274,6 +1274,47 @@ interface ResolvedSectionsCache {
1274
1274
  const resolvedLayoutCache = createCacheStore<ResolvedSectionsCache>("resolved-layouts");
1275
1275
  const resolvedLayoutInflight = new Map<string, Promise<ResolvedSection[]>>();
1276
1276
 
1277
+ /**
1278
+ * Single-flight for resolved layouts (Header/Footer — every page joins it).
1279
+ * A slot whose owner request was cancelled never settles (its I/O and its
1280
+ * `withInflightTimeout` timer die with that request), so joiners are bounded
1281
+ * by their own timer (`joinInflight`), the owner's work is kept alive with
1282
+ * `waitUntil` (`cacheBackground`) and the slot is released by identity.
1283
+ */
1284
+ function sharedResolvedLayout(
1285
+ cacheKey: string,
1286
+ run: () => Promise<ResolvedSection[]>,
1287
+ ): Promise<ResolvedSection[]> {
1288
+ const inflight = resolvedLayoutInflight.get(cacheKey);
1289
+ if (inflight) {
1290
+ return joinInflight(
1291
+ inflight,
1292
+ () => {
1293
+ if (resolvedLayoutInflight.get(cacheKey) === inflight)
1294
+ resolvedLayoutInflight.delete(cacheKey);
1295
+ // A newer flight may have filled the cache while this one stalled.
1296
+ return getCachedResolvedLayout(cacheKey).then(
1297
+ (cached) => cached ?? sharedResolvedLayout(cacheKey, run),
1298
+ );
1299
+ },
1300
+ undefined,
1301
+ `resolvedLayout ${cacheKey}`,
1302
+ );
1303
+ }
1304
+ const p: Promise<ResolvedSection[]> = withInflightTimeout(
1305
+ run().then((results) => {
1306
+ setCachedResolvedLayout(cacheKey, results);
1307
+ return results;
1308
+ }),
1309
+ `resolvedLayout ${cacheKey}`,
1310
+ ).finally(() => {
1311
+ if (resolvedLayoutInflight.get(cacheKey) === p) resolvedLayoutInflight.delete(cacheKey);
1312
+ });
1313
+ cacheBackground(p);
1314
+ resolvedLayoutInflight.set(cacheKey, p);
1315
+ return p;
1316
+ }
1317
+
1277
1318
  /**
1278
1319
  * Cache key for a resolved layout block, segmented by DEVICE.
1279
1320
  *
@@ -2535,18 +2576,7 @@ async function resolveDecoPageImpl(
2535
2576
  const cached = await getCachedResolvedLayout(cacheKey);
2536
2577
  if (cached) return cached;
2537
2578
 
2538
- const inflight = resolvedLayoutInflight.get(cacheKey);
2539
- if (inflight) return inflight;
2540
-
2541
- const p = withInflightTimeout(
2542
- resolveRawSection(section, rctx).then((results) => {
2543
- setCachedResolvedLayout(cacheKey, results);
2544
- return results;
2545
- }),
2546
- `resolvedLayout ${cacheKey}`,
2547
- ).finally(() => resolvedLayoutInflight.delete(cacheKey));
2548
- resolvedLayoutInflight.set(cacheKey, p);
2549
- return p;
2579
+ return sharedResolvedLayout(cacheKey, () => resolveRawSection(section, rctx));
2550
2580
  }
2551
2581
 
2552
2582
  return resolveRawSection(section, rctx);
@@ -2641,18 +2671,7 @@ export async function resolvePageSections(
2641
2671
  const cached = await getCachedResolvedLayout(cacheKey);
2642
2672
  if (cached) return cached;
2643
2673
 
2644
- const inflight = resolvedLayoutInflight.get(cacheKey);
2645
- if (inflight) return inflight;
2646
-
2647
- const p = withInflightTimeout(
2648
- resolveRawSection(section, rctx).then((results) => {
2649
- setCachedResolvedLayout(cacheKey, results);
2650
- return results;
2651
- }),
2652
- `resolvedLayout ${cacheKey}`,
2653
- ).finally(() => resolvedLayoutInflight.delete(cacheKey));
2654
- resolvedLayoutInflight.set(cacheKey, p);
2655
- return p;
2674
+ return sharedResolvedLayout(cacheKey, () => resolveRawSection(section, rctx));
2656
2675
  }
2657
2676
 
2658
2677
  return resolveRawSection(section, rctx);
@@ -13,7 +13,46 @@ import { RequestContext } from "@decocms/blocks/sdk/requestContext";
13
13
  import { getCacheProfile } from "../sdk/cacheHeaders";
14
14
  import { cacheBackground, createCacheStore, getCacheStorageContext } from "../sdk/cacheStorage";
15
15
  import { detectDevice } from "../sdk/detectDevice";
16
- import { withInflightTimeout } from "../sdk/inflightTimeout";
16
+ import { joinInflight, withInflightTimeout } from "../sdk/inflightTimeout";
17
+
18
+ /**
19
+ * A slot whose owner request was cancelled never settles: its I/O and its
20
+ * `withInflightTimeout` timer die with that request. Joiners are bounded by
21
+ * their own timer (`joinInflight`), the owner's work is kept alive with
22
+ * `waitUntil` (`cacheBackground`), and the slot is released by identity so a
23
+ * late `finally` never evicts a newer flight. Same pair `cachedLoader` uses.
24
+ */
25
+ function joinSlot<T>(
26
+ map: Map<string, Promise<T>>,
27
+ key: string,
28
+ shared: Promise<T>,
29
+ rerun: () => Promise<T>,
30
+ label: string,
31
+ ): Promise<T> {
32
+ return joinInflight(
33
+ shared,
34
+ () => {
35
+ if (map.get(key) === shared) map.delete(key);
36
+ return rerun();
37
+ },
38
+ undefined,
39
+ label,
40
+ );
41
+ }
42
+
43
+ function publishSlot<T>(
44
+ map: Map<string, Promise<T>>,
45
+ key: string,
46
+ promise: Promise<T>,
47
+ ): Promise<T> {
48
+ const tracked: Promise<T> = promise.finally(() => {
49
+ if (map.get(key) === tracked) map.delete(key);
50
+ });
51
+ cacheBackground(tracked);
52
+ map.set(key, tracked);
53
+ return tracked;
54
+ }
55
+
17
56
  import { withTracing } from "../sdk/observability";
18
57
  import type { ResolvedSection } from "./resolve";
19
58
  import { buildSectionLoaderContext, type SectionLoaderContext } from "./sectionLoaderContext";
@@ -145,14 +184,16 @@ async function runCacheableSectionLoader(
145
184
  sectionCacheKey(section.component, section.props as Record<string, unknown>),
146
185
  );
147
186
 
187
+ const rerun = () => runCacheableSectionLoader(section, loader, request, config);
148
188
  const existing = sectionLoaderInflight.get(key);
149
- if (existing) return existing;
189
+ if (existing)
190
+ return joinSlot(sectionLoaderInflight, key, existing, rerun, `sectionLoader ${key}`);
150
191
 
151
192
  const entry = getCacheStorageContext()?.storage
152
193
  ? await sectionLoaderCache.read(key)
153
194
  : sectionLoaderCache.get(key);
154
195
  const pending = sectionLoaderInflight.get(key);
155
- if (pending) return pending;
196
+ if (pending) return joinSlot(sectionLoaderInflight, key, pending, rerun, `sectionLoader ${key}`);
156
197
  const now = Date.now();
157
198
  const isStale = entry ? now - entry.createdAt > config.maxAge : true;
158
199
 
@@ -202,10 +243,9 @@ async function runCacheableSectionLoader(
202
243
  return enriched;
203
244
  })(),
204
245
  `sectionLoader ${key}`,
205
- ).finally(() => sectionLoaderInflight.delete(key));
246
+ );
206
247
 
207
- sectionLoaderInflight.set(key, promise);
208
- return promise;
248
+ return publishSlot(sectionLoaderInflight, key, promise);
209
249
  }
210
250
 
211
251
  /**
@@ -386,7 +426,15 @@ async function resolveLayoutSection(
386
426
  if (cached) return Promise.resolve(withIndex(cached));
387
427
 
388
428
  const existing = layoutInflight.get(key);
389
- if (existing) return existing.then(withIndex);
429
+ if (existing) {
430
+ return joinSlot(
431
+ layoutInflight,
432
+ key,
433
+ existing,
434
+ () => resolveLayoutSection(section, loader, request),
435
+ `layoutSection ${key}`,
436
+ ).then(withIndex);
437
+ }
390
438
 
391
439
  const promise = withInflightTimeout(
392
440
  (async () => {
@@ -397,11 +445,9 @@ async function resolveLayoutSection(
397
445
  return withIndex(enriched);
398
446
  })(),
399
447
  `layoutSection ${key}`,
400
- ).finally(() => layoutInflight.delete(key));
401
-
402
- layoutInflight.set(key, promise);
448
+ );
403
449
 
404
- return promise;
450
+ return publishSlot(layoutInflight, key, promise);
405
451
  }
406
452
 
407
453
  /**
@@ -139,6 +139,40 @@ it("data stores key by dataScope and survive a deploy; build stores do not", asy
139
139
  expect(await run(storage, "site:build-B", () => data2.read(data2.key("item")))).toBeUndefined();
140
140
  });
141
141
 
142
+ it("cachedLoader with dataVersion survives a deploy/publish; without it, it does not", async () => {
143
+ const storage = createKVCacheStorage(fakeKV());
144
+ const bind = <T,>(build: string, fn: () => T): T =>
145
+ RequestContext.run(new Request("https://site.test/"), () => {
146
+ bindCacheStorage({
147
+ storage,
148
+ scope: `site:${build}`,
149
+ dataScope: "site:data:1",
150
+ waitUntil: (work) => pending.push(work),
151
+ });
152
+ return fn();
153
+ });
154
+ const opts = { policy: "stale-while-revalidate", maxAge: 60_000 } as const;
155
+ const fn = vi.fn(async (p: { q: string }) => ({ q: p.q }));
156
+ const data = createCachedLoader("plp", fn, { ...opts, dataVersion: "1" });
157
+ const build = createCachedLoader("plp-build", fn, opts);
158
+ await bind("build-A", async () => {
159
+ await data({ q: "a" });
160
+ await build({ q: "a" });
161
+ await flush();
162
+ });
163
+ expect(fn).toHaveBeenCalledTimes(2);
164
+ clearLoaderCache();
165
+ await bind("build-B", () => data({ q: "a" }));
166
+ expect(fn).toHaveBeenCalledTimes(2); // preserved across the new build
167
+ await bind("build-B", () => build({ q: "a" }));
168
+ expect(fn).toHaveBeenCalledTimes(3); // per-build entry is gone
169
+ // Bumping dataVersion (shape change) or new props miss.
170
+ const bumped = createCachedLoader("plp", fn, { ...opts, dataVersion: "2" });
171
+ await bind("build-B", () => bumped({ q: "a" }));
172
+ await bind("build-B", () => data({ q: "b" }));
173
+ expect(fn).toHaveBeenCalledTimes(5);
174
+ });
175
+
142
176
  it("does not switch bindings between concurrent requests", async () => {
143
177
  const a = createMemoryCacheStorage();
144
178
  const b = createMemoryCacheStorage();
@@ -238,9 +238,10 @@ export function createCacheStore<T>(
238
238
  return entry.value;
239
239
  }
240
240
  return {
241
- key(raw: string): string {
241
+ /** `keyKind` overrides the store's `kind` for this key (same memory tier and budget). */
242
+ key(raw: string, keyKind: "build" | "data" = kind): string {
242
243
  const context = getCacheStorageContext();
243
- const scope = (kind === "data" ? context?.dataScope : undefined) ?? context?.scope;
244
+ const scope = (keyKind === "data" ? context?.dataScope : undefined) ?? context?.scope;
244
245
  return JSON.stringify([scope ?? "local", namespace, raw]);
245
246
  },
246
247
  get,
@@ -64,6 +64,21 @@ export interface CachedLoaderOptions {
64
64
  * Default: every resolved result is stored.
65
65
  */
66
66
  shouldCache?: (result: unknown) => boolean;
67
+ /**
68
+ * Opt this loader's results out of the per-build key. When set, entries are
69
+ * keyed by `dataVersion` instead of the build hash and stored in the request's
70
+ * data scope — which, with `DECO_DATA_CACHE_ON_DEPLOY=preserve`, excludes the
71
+ * build hash and CMS revision, so results survive deploys and publishes
72
+ * (props are still part of the key). Without preserve it behaves as before.
73
+ *
74
+ * Only for loaders whose result is a pure function of props + upstream data:
75
+ * a CMS publish no longer invalidates these entries, so a loader that reads
76
+ * decofile data outside its props would keep the old result until its TTL.
77
+ * Bump the string whenever the result's shape/transform changes: a forgotten
78
+ * bump serves the old shape to the new code until the entry expires. Purge
79
+ * with `DECO_DATA_CACHE_PURGE` or `cache:data-version` in DECO_KV.
80
+ */
81
+ dataVersion?: string;
67
82
  }
68
83
 
69
84
  /**
@@ -280,7 +295,9 @@ export function createCachedLoader<TProps, TResult>(
280
295
  staleWhileRevalidate = 300_000,
281
296
  keyFn = JSON.stringify,
282
297
  shouldCache,
298
+ dataVersion,
283
299
  } = resolved;
300
+ const keyVersion = dataVersion === undefined ? BUILD : `data:${dataVersion}`;
284
301
 
285
302
  const env = typeof globalThis.process !== "undefined" ? globalThis.process.env : undefined;
286
303
  const isDev = env?.DECO_CACHE_DISABLE === "true" || env?.NODE_ENV === "development";
@@ -297,15 +314,23 @@ export function createCachedLoader<TProps, TResult>(
297
314
  if (policy === "no-store") return loaderFn;
298
315
 
299
316
  const cachedFn = async (props: TProps): Promise<TResult> => {
300
- const cacheKey = cache.key(`${BUILD}::${name}::${keyFn(props)}`);
317
+ const cacheKey = cache.key(
318
+ `${keyVersion}::${name}::${keyFn(props)}`,
319
+ dataVersion === undefined ? "build" : "data",
320
+ );
301
321
  // Joining another caller's flight is bounded by a timer of THIS caller's
302
322
  // request (see `joinInflight`): if the owner's request was cancelled and
303
323
  // its Promise will never settle, evict the dead slot and run again.
304
324
  const join = (shared: Promise<unknown>): Promise<TResult> =>
305
- joinInflight(shared as Promise<TResult>, () => {
306
- releaseSlot(inflightRequests, cacheKey, shared);
307
- return cachedFn(props);
308
- });
325
+ joinInflight(
326
+ shared as Promise<TResult>,
327
+ () => {
328
+ releaseSlot(inflightRequests, cacheKey, shared);
329
+ return cachedFn(props);
330
+ },
331
+ undefined,
332
+ `cachedLoader ${cacheKey}`,
333
+ );
309
334
  const retention =
310
335
  maxAge +
311
336
  Math.max(staleIfError, policy === "stale-while-revalidate" ? staleWhileRevalidate : 0);
@@ -549,10 +574,15 @@ export function createCachedLoaderFromModule<TProps, TResult>(
549
574
  if (existing) {
550
575
  // Bounded by this caller's own timer: a flight whose owner request was
551
576
  // cancelled never settles — evict it and run again (see `joinInflight`).
552
- return joinInflight(existing, () => {
553
- releaseSlot(moduleInflight, key, existing);
554
- return dedupedFn(props, req, ctx);
555
- });
577
+ return joinInflight(
578
+ existing,
579
+ () => {
580
+ releaseSlot(moduleInflight, key, existing);
581
+ return dedupedFn(props, req, ctx);
582
+ },
583
+ undefined,
584
+ `dedupLoader ${key}`,
585
+ );
556
586
  }
557
587
 
558
588
  const promise: Promise<TResult> = Promise.resolve(mod.default(props, req, ctx)).finally(() => {
@@ -204,3 +204,78 @@ describe("createFetchCache — shared storage scope", () => {
204
204
  expect(await acrossDeploy(undefined)).toEqual({ body: { ok: true }, calls: 2 });
205
205
  });
206
206
  });
207
+
208
+ // Workers cancels a request's I/O AND timers when its client disconnects. A
209
+ // flight whose owner was cancelled never settles, so its own backstop timer
210
+ // never fires either — every caller that joined it used to hang for the life
211
+ // of the isolate (CPU ~0, wall 100s → 524). Simulated here: the owner's fetch
212
+ // never resolves and its timers are swallowed while it arms them.
213
+ describe("fetchCache — cancelled owner", () => {
214
+ it("a joiner recovers on its own timer instead of hanging on the dead slot", async () => {
215
+ const fc = createFetchCache({
216
+ provider: "cancelled-owner",
217
+ maxEntries: 10,
218
+ freshTtlMs: { success: 60_000, notFound: 0, serverError: 0 },
219
+ staleIfErrorMs: 0,
220
+ inflightBackstopMs: 100,
221
+ });
222
+ let calls = 0;
223
+ const doFetch = () =>
224
+ ++calls === 1
225
+ ? new Promise<Response>(() => {})
226
+ : Promise.resolve(Response.json({ ok: true }));
227
+
228
+ const realSetTimeout = globalThis.setTimeout;
229
+ (globalThis as { setTimeout: unknown }).setTimeout = () => 0;
230
+ try {
231
+ void fc.fetchWithCache("k", doFetch);
232
+ } finally {
233
+ globalThis.setTimeout = realSetTimeout;
234
+ }
235
+
236
+ const res = await Promise.race([
237
+ fc.fetchWithCache("k", doFetch),
238
+ new Promise((r) => setTimeout(() => r("HUNG"), 2_000)),
239
+ ]);
240
+ expect(res).toEqual({ ok: true });
241
+ expect(calls).toBe(2);
242
+ });
243
+
244
+ it("a joiner that stalls is counted once, by its retry, not as a HIT too", async () => {
245
+ const { adapter, counters } = captureMeter();
246
+ configureMeter(adapter);
247
+ try {
248
+ const fc = createFetchCache({
249
+ provider: "stalled-joiner",
250
+ maxEntries: 10,
251
+ freshTtlMs: { success: 60_000, notFound: 0, serverError: 0 },
252
+ staleIfErrorMs: 0,
253
+ inflightBackstopMs: 100,
254
+ });
255
+ let calls = 0;
256
+ const doFetch = () =>
257
+ ++calls === 1
258
+ ? new Promise<Response>(() => {})
259
+ : Promise.resolve(Response.json({ ok: true }));
260
+
261
+ const realSetTimeout = globalThis.setTimeout;
262
+ (globalThis as { setTimeout: unknown }).setTimeout = () => 0;
263
+ try {
264
+ void fc.fetchWithCache("k", doFetch);
265
+ } finally {
266
+ globalThis.setTimeout = realSetTimeout;
267
+ }
268
+ counters.length = 0;
269
+
270
+ await fc.fetchWithCache("k", doFetch);
271
+ const decisions = counters
272
+ .filter(
273
+ (c) => c.name === "deco.cache.requests" && c.labels?.["provider"] === "stalled-joiner",
274
+ )
275
+ .map((c) => c.labels?.["status"]);
276
+ expect(decisions).toEqual(["MISS"]);
277
+ } finally {
278
+ configureMeter({ counterInc: () => {} });
279
+ }
280
+ });
281
+ });
@@ -29,6 +29,7 @@
29
29
 
30
30
  import { type CacheDecision, recordCacheMetric } from "../middleware/observability";
31
31
  import { cacheBackground, createCacheStore, getCacheStorageContext } from "./cacheStorage";
32
+ import { joinInflight } from "./inflightTimeout";
32
33
 
33
34
  /** Fresh-TTL (ms) by HTTP status class. See {@link FetchCacheConfig}. */
34
35
  export interface FreshTtlByStatus {
@@ -171,6 +172,7 @@ export function createFetchCache(config: FetchCacheConfig): FetchCache {
171
172
  doFetch: () => Promise<Response>,
172
173
  opts?: FetchCacheOptions,
173
174
  ): Promise<T | null> {
175
+ const inputKey = cacheKey;
174
176
  cacheKey = store.key(cacheKey);
175
177
  const entry = getCacheStorageContext()?.storage
176
178
  ? await store.read(cacheKey)
@@ -237,8 +239,25 @@ export function createFetchCache(config: FetchCacheConfig): FetchCache {
237
239
  const existing = inflight.get(cacheKey);
238
240
  if (existing) {
239
241
  // Joined an in-flight upstream fetch — no upstream call of our own.
240
- emit("HIT");
241
- return existing.then((e) => e.body as T | null);
242
+ // Bounded by THIS caller's timer: if the owner request was cancelled its
243
+ // fetch (and its backstop timer) died with it and `existing` never
244
+ // settles — evict the dead slot and fetch again (see `joinInflight`).
245
+ // The join counts as a HIT only when it is answered by the shared fetch:
246
+ // after a stall the retry records its own decision.
247
+ let stalled = false;
248
+ return joinInflight(
249
+ existing.then((e) => {
250
+ if (!stalled) emit("HIT");
251
+ return e.body as T | null;
252
+ }),
253
+ () => {
254
+ stalled = true;
255
+ if (inflight.get(cacheKey) === existing) inflight.delete(cacheKey);
256
+ return fetchWithCache<T>(inputKey, doFetch, opts);
257
+ },
258
+ inflightBackstopMs,
259
+ `fetchCache ${cacheKey}`,
260
+ );
242
261
  }
243
262
 
244
263
  // Cold miss: run the loader. Wrap with a timeout so `.finally()` always
@@ -256,8 +275,13 @@ export function createFetchCache(config: FetchCacheConfig): FetchCache {
256
275
  }
257
276
  return fresh;
258
277
  })
259
- .finally(() => inflight.delete(cacheKey));
278
+ .finally(() => {
279
+ if (inflight.get(cacheKey) === promise) inflight.delete(cacheKey);
280
+ });
260
281
 
282
+ // Keep the shared fetch alive past its owner request (client disconnect)
283
+ // so joiners still get the answer.
284
+ cacheBackground(promise);
261
285
  inflight.set(cacheKey, promise);
262
286
  return promise.then((e) => e.body as T | null);
263
287
  }
@@ -1,5 +1,5 @@
1
1
  import { describe, expect, it, vi } from "vitest";
2
- import { DEFAULT_INFLIGHT_TIMEOUT_MS, withInflightTimeout } from "./inflightTimeout";
2
+ import { DEFAULT_INFLIGHT_TIMEOUT_MS, joinInflight, withInflightTimeout } from "./inflightTimeout";
3
3
 
4
4
  describe("withInflightTimeout", () => {
5
5
  it("returns the underlying value when work settles in time", async () => {
@@ -33,3 +33,29 @@ describe("withInflightTimeout", () => {
33
33
  expect(DEFAULT_INFLIGHT_TIMEOUT_MS).toBeLessThanOrEqual(60_000);
34
34
  });
35
35
  });
36
+
37
+ describe("joinInflight — stall signal", () => {
38
+ it("logs one `[inflight] stall` with the label when the joiner gives up", async () => {
39
+ vi.useFakeTimers();
40
+ const warn = vi.spyOn(console, "warn").mockImplementation(() => {});
41
+ try {
42
+ const joined = joinInflight(
43
+ new Promise<string>(() => {}),
44
+ async () => "rerun",
45
+ 50,
46
+ "layoutSection k",
47
+ );
48
+ await vi.advanceTimersByTimeAsync(50);
49
+ expect(await joined).toBe("rerun");
50
+ expect(warn).toHaveBeenCalledTimes(1);
51
+ expect(warn.mock.calls[0][0]).toBe("[inflight] stall");
52
+ expect(JSON.parse(warn.mock.calls[0][1] as string)).toEqual({
53
+ label: "layoutSection k",
54
+ waitedMs: 50,
55
+ });
56
+ } finally {
57
+ warn.mockRestore();
58
+ vi.useRealTimers();
59
+ }
60
+ });
61
+ });
@@ -40,11 +40,7 @@ export function withInflightTimeout<T>(
40
40
  let timer: ReturnType<typeof setTimeout> | undefined;
41
41
  const timeout = new Promise<never>((_, reject) => {
42
42
  timer = setTimeout(() => {
43
- reject(
44
- new Error(
45
- `[blocks] inflight cache entry "${label}" timed out after ${ms}ms`,
46
- ),
47
- );
43
+ reject(new Error(`[blocks] inflight cache entry "${label}" timed out after ${ms}ms`));
48
44
  }, ms);
49
45
  });
50
46
  return Promise.race([work, timeout]).finally(() => {
@@ -72,9 +68,17 @@ export function joinInflight<T>(
72
68
  shared: Promise<T>,
73
69
  onStall: () => Promise<T>,
74
70
  ms: number = DEFAULT_INFLIGHT_TIMEOUT_MS,
71
+ label?: string,
75
72
  ): Promise<T> {
76
73
  return new Promise<T>((resolve, reject) => {
77
74
  const timer = setTimeout(() => {
75
+ // Observable signal: a joiner gave up on a shared flight. Steady volume
76
+ // means owners are being cancelled (client disconnects) or are slower
77
+ // than `ms`; a burst on one label is a poisoned key. Grep "[inflight] stall".
78
+ console.warn(
79
+ "[inflight] stall",
80
+ JSON.stringify({ label: label?.slice(0, 200) ?? null, waitedMs: ms }),
81
+ );
78
82
  // `onStall` may throw synchronously (a non-async loader wrapper); route it
79
83
  // into the Promise chain so the joiner rejects instead of hanging.
80
84
  Promise.resolve().then(onStall).then(resolve, reject);