@c9up/echo 0.1.15 → 0.2.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.
Files changed (44) hide show
  1. package/dist/CacheManager.d.ts +52 -6
  2. package/dist/CacheManager.d.ts.map +1 -1
  3. package/dist/CacheManager.js +146 -6
  4. package/dist/CacheManager.js.map +1 -1
  5. package/dist/EchoProvider.d.ts +27 -1
  6. package/dist/EchoProvider.d.ts.map +1 -1
  7. package/dist/EchoProvider.js +31 -3
  8. package/dist/EchoProvider.js.map +1 -1
  9. package/dist/StoreManager.d.ts +25 -2
  10. package/dist/StoreManager.d.ts.map +1 -1
  11. package/dist/StoreManager.js +35 -1
  12. package/dist/StoreManager.js.map +1 -1
  13. package/dist/drivers/MemoryDriver.d.ts +1 -1
  14. package/dist/drivers/MemoryDriver.d.ts.map +1 -1
  15. package/dist/drivers/MemoryDriver.js +19 -3
  16. package/dist/drivers/MemoryDriver.js.map +1 -1
  17. package/dist/drivers/RedisDriver.d.ts +1 -1
  18. package/dist/drivers/RedisDriver.d.ts.map +1 -1
  19. package/dist/drivers/RedisDriver.js +5 -2
  20. package/dist/drivers/RedisDriver.js.map +1 -1
  21. package/dist/drivers/TieredDriver.d.ts +45 -3
  22. package/dist/drivers/TieredDriver.d.ts.map +1 -1
  23. package/dist/drivers/TieredDriver.js +77 -10
  24. package/dist/drivers/TieredDriver.js.map +1 -1
  25. package/dist/quasar.d.ts +7 -6
  26. package/dist/quasar.d.ts.map +1 -1
  27. package/dist/quasar.js +96 -68
  28. package/dist/quasar.js.map +1 -1
  29. package/dist/types.d.ts +26 -1
  30. package/dist/types.d.ts.map +1 -1
  31. package/dist/vendor/quasarConnection.d.ts +35 -0
  32. package/dist/vendor/quasarConnection.d.ts.map +1 -0
  33. package/dist/vendor/quasarConnection.js +62 -0
  34. package/dist/vendor/quasarConnection.js.map +1 -0
  35. package/package.json +1 -1
  36. package/src/CacheManager.ts +163 -12
  37. package/src/EchoProvider.ts +32 -3
  38. package/src/StoreManager.ts +52 -3
  39. package/src/drivers/MemoryDriver.ts +16 -3
  40. package/src/drivers/RedisDriver.ts +5 -2
  41. package/src/drivers/TieredDriver.ts +108 -11
  42. package/src/quasar.ts +123 -87
  43. package/src/types.ts +26 -1
  44. package/src/vendor/quasarConnection.ts +129 -0
@@ -87,8 +87,13 @@ function withTimeout<T>(
87
87
  export interface CacheConfig {
88
88
  driver?: string;
89
89
  prefix?: string;
90
- /** Default TTL in **seconds** (echo-native unit; see `duration.ts`). */
91
- ttl?: number;
90
+ /**
91
+ * How long an entry stays fresh: a number of SECONDS, or a
92
+ * {@link Duration} — `'30s'`, `'10m'` — like every other timing option
93
+ * here. It was the one locked to `number`, so a config copied from the
94
+ * documentation failed to typecheck on the line most likely to be copied.
95
+ */
96
+ ttl?: Duration;
92
97
  /** Default grace period (stale-while-revalidate) as a {@link Duration}. */
93
98
  grace?: Duration;
94
99
  /** Default soft timeout for `getOrSet` (return stale if the factory is slower). */
@@ -120,6 +125,13 @@ interface NormalizedGetOrSet<T> {
120
125
  onFactoryError?: (error: FactoryError) => void;
121
126
  }
122
127
 
128
+ /** The slice of `CacheStoreManager` a store it built needs to reach back into. */
129
+ export interface StoreFacade {
130
+ use(name?: string): CacheManager;
131
+ connectAll(): Promise<void>;
132
+ disconnectAll(): Promise<void>;
133
+ }
134
+
123
135
  export class CacheManager {
124
136
  #driver: CacheDriver;
125
137
  #prefix: string;
@@ -144,11 +156,24 @@ export class CacheManager {
144
156
  "cache:cleared": new Set(),
145
157
  };
146
158
  #shared: SharedState;
159
+ /**
160
+ * The store manager this one came from, when it did.
161
+ *
162
+ * What makes `cache.use('other')` work on the object the provider
163
+ * publishes. Upstream's manager is ONE object that both operates on the
164
+ * default store and reaches the named ones; binding the default store
165
+ * alone made the first example in the README throw on its second line.
166
+ */
167
+ #stores: StoreFacade | undefined;
168
+ /** A connect in flight, so two callers do not open two. */
169
+ #connecting: Promise<void> | undefined;
170
+ /** Whether the driver's external work is open. Reset by `disconnect()`. */
171
+ #connected = false;
147
172
 
148
173
  constructor(driver: CacheDriver, config?: CacheConfig, shared?: SharedState) {
149
174
  this.#driver = driver;
150
175
  this.#prefix = config?.prefix ?? "";
151
- this.#defaultTtl = config?.ttl ?? 3600;
176
+ this.#defaultTtl = resolveTtlSeconds(config?.ttl, 3600);
152
177
  this.#defaultGrace = config?.grace;
153
178
  this.#defaultTimeout = config?.timeout;
154
179
  this.#defaultHardTimeout = config?.hardTimeout;
@@ -241,6 +266,7 @@ export class CacheManager {
241
266
  * A driver without the hook reports nothing pruned rather than failing.
242
267
  */
243
268
  async prune(): Promise<void> {
269
+ await this.#whenConnected();
244
270
  await this.#driver.prune?.();
245
271
  }
246
272
 
@@ -251,8 +277,108 @@ export class CacheManager {
251
277
  * the connection and other consumers may still be using it. Only a driver
252
278
  * that owns its resource implements the hook.
253
279
  */
280
+ /**
281
+ * Reach a named store — or this one, when it is the only one.
282
+ *
283
+ * @throws when a name is given and this manager owns a single store: the
284
+ * configuration says which stores exist, and answering with the default
285
+ * would cache under a name nobody declared.
286
+ */
287
+ use(name?: string): CacheManager {
288
+ if (this.#stores) return this.#stores.use(name);
289
+ if (name === undefined) return this;
290
+ throw new Error(
291
+ `Echo: cannot use the "${name}" store — this cache is configured with a single store. ` +
292
+ "Declare `{ default, stores }` in config/cache.ts to name several.",
293
+ );
294
+ }
295
+
296
+ /** @internal Called by `CacheStoreManager` on the store it builds. */
297
+ belongsTo(stores: StoreFacade): void {
298
+ this.#stores = stores;
299
+ }
300
+
301
+ /**
302
+ * Open what the driver needs outside the process (a bus subscription).
303
+ *
304
+ * Awaited by whoever readies the application, and its failure is theirs to
305
+ * refuse — a tiered store that never subscribed serves stale L1 copies to
306
+ * everyone until their TTL.
307
+ */
308
+ async connect(): Promise<void> {
309
+ if (this.#connected) return;
310
+ // Once. Two callers — the provider readying, and the first operation on
311
+ // a store built after that — must not open two subscriptions.
312
+ this.#connecting ??= (async () => {
313
+ await this.#driver.connect?.();
314
+ this.#connected = true;
315
+ })();
316
+ try {
317
+ await this.#connecting;
318
+ } finally {
319
+ // Forgotten either way. On failure so a later call gets to try again
320
+ // rather than replaying the same rejection for the life of the
321
+ // process; on success because `#connected` is what says so, and a
322
+ // memo kept past a `disconnect()` made the next `connect()` a no-op
323
+ // on a connection that had since been closed.
324
+ this.#connecting = undefined;
325
+ }
326
+ }
327
+
328
+ /**
329
+ * Wait for a connect ALREADY under way, and let its failure pass.
330
+ *
331
+ * A store built after the application was ready connects on its way out of
332
+ * `use()`, and its first operation must not race that. The failure is not
333
+ * this caller's to raise: the provider refuses the boot when the bus cannot
334
+ * be reached, and after that an unreachable bus costs staleness — refusing
335
+ * every read would cost far more.
336
+ */
337
+ async #whenConnected(): Promise<void> {
338
+ if (this.#connected) return;
339
+ // STARTED here, not merely awaited. A store built after the application
340
+ // was ready connects on its way out of `use()`, and a connect that
341
+ // failed leaves nothing in flight — so an operation that only waited
342
+ // went on to read and write off the bus, for good. Attempting it means
343
+ // a transient failure is retried by the next operation instead.
344
+ //
345
+ // The failure is not raised: the provider refuses the boot when the bus
346
+ // cannot be reached, and after that an unreachable bus costs staleness.
347
+ // Refusing every read would cost far more.
348
+ await this.connect().catch(() => {});
349
+ }
350
+
351
+ /**
352
+ * Open every store this cache can reach, the named ones included.
353
+ *
354
+ * `connect()` alone reaches the DEFAULT store, which is what the provider
355
+ * publishes — so a named tiered store declared beside it never subscribed,
356
+ * and its L1 kept serving copies of keys other instances had deleted.
357
+ */
358
+ async connectAll(): Promise<void> {
359
+ if (this.#stores) return this.#stores.connectAll();
360
+ await this.connect();
361
+ }
362
+
363
+ /** Release every store this cache can reach (bentocache `disconnectAll`). */
364
+ async disconnectAll(): Promise<void> {
365
+ if (this.#stores) return this.#stores.disconnectAll();
366
+ await this.disconnect();
367
+ }
368
+
254
369
  async disconnect(): Promise<void> {
255
- await this.#driver.disconnect?.();
370
+ // A connect still in flight finishes FIRST, so its subscription is one
371
+ // this teardown can see. Tearing down ahead of it left the handler to
372
+ // land afterwards, on a store nobody was tracking any more.
373
+ if (this.#connecting) await this.#connecting.catch(() => {});
374
+ try {
375
+ await this.#driver.disconnect?.();
376
+ } finally {
377
+ // Reset either way: a store that refused to close is not one that
378
+ // should silently skip its next `connect()`.
379
+ this.#connected = false;
380
+ this.#connecting = undefined;
381
+ }
256
382
  }
257
383
 
258
384
  async #readEntry<T>(prefixed: string): Promise<CacheEntry<T> | null> {
@@ -297,11 +423,12 @@ export class CacheManager {
297
423
 
298
424
  // ---- get -------------------------------------------------------------
299
425
 
300
- get<T = unknown>(key: string): Promise<T | null>;
301
- get<T = unknown>(options: GetOptions<T>): Promise<T | null>;
426
+ get<T = unknown>(key: string): Promise<T | undefined>;
427
+ get<T = unknown>(options: GetOptions<T>): Promise<T | undefined>;
302
428
  async get<T = unknown>(
303
429
  keyOrOptions: string | GetOptions<T>,
304
- ): Promise<T | null> {
430
+ ): Promise<T | undefined> {
431
+ await this.#whenConnected();
305
432
  const key =
306
433
  typeof keyOrOptions === "string" ? keyOrOptions : keyOrOptions.key;
307
434
  const graceSeconds =
@@ -335,7 +462,12 @@ export class CacheManager {
335
462
  if (defaultValue !== undefined) {
336
463
  return defaultValue instanceof Function ? defaultValue() : defaultValue;
337
464
  }
338
- return null;
465
+ // UNDEFINED, as upstream answers. It returned `null`, so code written
466
+ // against the documented shape — `if (value === undefined)` — never
467
+ // matched a miss, silently. The driver boundary still speaks `null`,
468
+ // which is where the translation happens: a driver reports "no entry",
469
+ // and this reports "nothing cached".
470
+ return undefined;
339
471
  }
340
472
 
341
473
  // ---- set -------------------------------------------------------------
@@ -347,6 +479,7 @@ export class CacheManager {
347
479
  value?: unknown,
348
480
  ttlSeconds?: number,
349
481
  ): Promise<void> {
482
+ await this.#whenConnected();
350
483
  let key: string;
351
484
  let val: unknown;
352
485
  let ttl: number;
@@ -382,6 +515,7 @@ export class CacheManager {
382
515
  delete(key: string): Promise<boolean>;
383
516
  delete(options: DeleteOptions): Promise<boolean>;
384
517
  async delete(keyOrOptions: string | DeleteOptions): Promise<boolean> {
518
+ await this.#whenConnected();
385
519
  const key =
386
520
  typeof keyOrOptions === "string" ? keyOrOptions : keyOrOptions.key;
387
521
  const deleted = await this.#driver.delete(this.#prefixKey(key));
@@ -393,6 +527,7 @@ export class CacheManager {
393
527
  async deleteMany(
394
528
  keysOrOptions: string[] | DeleteManyOptions,
395
529
  ): Promise<boolean> {
530
+ await this.#whenConnected();
396
531
  const keys = Array.isArray(keysOrOptions)
397
532
  ? keysOrOptions
398
533
  : keysOrOptions.keys;
@@ -408,6 +543,7 @@ export class CacheManager {
408
543
  has(key: string): Promise<boolean>;
409
544
  has(options: HasOptions): Promise<boolean>;
410
545
  async has(keyOrOptions: string | HasOptions): Promise<boolean> {
546
+ await this.#whenConnected();
411
547
  const key =
412
548
  typeof keyOrOptions === "string" ? keyOrOptions : keyOrOptions.key;
413
549
  return this.#driver.has(this.#prefixKey(key));
@@ -421,9 +557,10 @@ export class CacheManager {
421
557
  }
422
558
 
423
559
  /** Read a key and delete it in one step (bento `pull`). Returns `null` on miss. */
424
- async pull<T = unknown>(key: string): Promise<T | null> {
560
+ async pull<T = unknown>(key: string): Promise<T | undefined> {
561
+ await this.#whenConnected();
425
562
  const value = await this.get<T>(key);
426
- if (value !== null) await this.delete(key);
563
+ if (value !== undefined) await this.delete(key);
427
564
  return value;
428
565
  }
429
566
 
@@ -432,6 +569,7 @@ export class CacheManager {
432
569
  * window (bento `expire`). Without grace this is equivalent to a delete.
433
570
  */
434
571
  async expire(keyOrOptions: string | ExpireOptions): Promise<boolean> {
572
+ await this.#whenConnected();
435
573
  const key =
436
574
  typeof keyOrOptions === "string" ? keyOrOptions : keyOrOptions.key;
437
575
  const prefixed = this.#prefixKey(key);
@@ -452,9 +590,19 @@ export class CacheManager {
452
590
  return this.#driver.delete(prefixed);
453
591
  }
454
592
 
455
- /** Clear the whole store (bento/Adonis `clear`). */
593
+ /**
594
+ * Clear this cache — the whole store, or only this namespace's subtree.
595
+ *
596
+ * A namespaced view shares the driver, so this used to flush everything:
597
+ * one tenant clearing its own cache emptied every other tenant's, from an
598
+ * operation they are allowed to run. Upstream scopes it the same way, by
599
+ * handing the driver the prefix.
600
+ */
456
601
  async clear(): Promise<void> {
457
- await this.#driver.flush();
602
+ await this.#whenConnected();
603
+ // The separator is part of it: `tenant-a` must not take `tenant-abc`
604
+ // with it, and every key under this view is written `<prefix>:<key>`.
605
+ await this.#driver.flush(this.#prefix ? `${this.#prefix}:` : undefined);
458
606
  this.#emit("cache:cleared", { store: this.#name });
459
607
  }
460
608
 
@@ -467,6 +615,7 @@ export class CacheManager {
467
615
  tags: string[],
468
616
  ttlSeconds?: number,
469
617
  ): Promise<void> {
618
+ await this.#whenConnected();
470
619
  await this.#writeValue(
471
620
  this.#prefixKey(key),
472
621
  value,
@@ -483,6 +632,7 @@ export class CacheManager {
483
632
  async deleteByTag(
484
633
  tagsOrOptions: string[] | DeleteByTagOptions,
485
634
  ): Promise<void> {
635
+ await this.#whenConnected();
486
636
  const tags = Array.isArray(tagsOrOptions)
487
637
  ? tagsOrOptions
488
638
  : tagsOrOptions.tags;
@@ -608,6 +758,7 @@ export class CacheManager {
608
758
  b?: number,
609
759
  c?: Factory<T>,
610
760
  ): Promise<T> {
761
+ await this.#whenConnected();
611
762
  const o = this.#normalizeGetOrSet<T>(a, b, c);
612
763
  const prefixed = this.#prefixKey(o.key);
613
764
 
@@ -116,16 +116,45 @@ export default class EchoProvider {
116
116
  this.app.container.singleton("cache", cache);
117
117
  }
118
118
 
119
- /** The cache THIS provider booted — not whatever the module singleton holds. */
119
+ /** The cache THIS provider opened — not whatever the module singleton holds. */
120
120
  #cache: CacheManager | undefined;
121
121
 
122
+ /**
123
+ * Publish the cache on `services/main`.
124
+ *
125
+ * At BOOT, matching upstream, whose own accessor resolves the manager on
126
+ * `app.booted()`. It has to be here: the HTTP socket opens before the
127
+ * providers are readied, so a cache published in `ready` left a window
128
+ * where a request could reach a controller and the accessor would throw —
129
+ * and a preload that actually uses the cache would fail outright.
130
+ *
131
+ * Building it opens nothing. A driver's external work lives behind
132
+ * {@link CacheDriver.connect}, which {@link ready} awaits.
133
+ */
122
134
  async boot(): Promise<void> {
123
135
  this.#cache = await this.app.container.resolve<CacheManager>(CacheManager);
124
136
  setCache(this.#cache);
125
137
  }
126
138
 
127
139
  /**
128
- * Release the cache the app booted.
140
+ * Open what the drivers need outside the process — a tiered store's bus.
141
+ *
142
+ * `ready` is the phase upstream reserves for operational effects, and the
143
+ * one an inspection never reaches: `register`, `boot` and `start` all run
144
+ * under `ream inspect`, and `shutdown` does not, so a subscription opened
145
+ * any earlier was a Redis connection left behind by a command that only
146
+ * meant to list the routes.
147
+ *
148
+ * A failure here fails the boot, deliberately. An instance whose bus never
149
+ * subscribed keeps serving its own L1 copies of keys other instances have
150
+ * already deleted, with nothing to say so.
151
+ */
152
+ async ready(): Promise<void> {
153
+ await this.#cache?.connectAll();
154
+ }
155
+
156
+ /**
157
+ * Release the cache the app opened.
129
158
  *
130
159
  * The memory driver runs a sweep on a timer and the redis driver holds a
131
160
  * connection. Neither is released on its own, so across a dev reload or a
@@ -133,7 +162,7 @@ export default class EchoProvider {
133
162
  */
134
163
  async shutdown(): Promise<void> {
135
164
  if (!this.#cache) return;
136
- await this.#cache.disconnect();
165
+ await this.#cache.disconnectAll();
137
166
  // Two applications can share a process — parallel tests, a hot reload.
138
167
  // The module singleton holds whichever booted last, so it is only ours
139
168
  // to clear while it still points at the cache this provider booted.
@@ -29,8 +29,15 @@ export type DriverFactory = () => CacheDriver;
29
29
  export interface StoreConfig {
30
30
  driver: DriverFactory;
31
31
  prefix?: string;
32
- /** Default TTL in seconds. */
33
- ttl?: number;
32
+ /**
33
+ * How long an entry stays fresh. A number of seconds, or a duration —
34
+ * `'30s'`, `'10m'`, `'1h'` — the way every other timing option here reads,
35
+ * and the way upstream's config is written.
36
+ *
37
+ * It was the one option locked to `number`, so a config copied from the
38
+ * documentation did not typecheck on the line most likely to be copied.
39
+ */
40
+ ttl?: Duration;
34
41
  grace?: Duration;
35
42
  timeout?: Duration;
36
43
  hardTimeout?: Duration;
@@ -39,6 +46,14 @@ export interface StoreConfig {
39
46
 
40
47
  export interface MultiStoreConfig {
41
48
  default: string;
49
+ /**
50
+ * The TTL every store inherits when it does not name its own.
51
+ *
52
+ * Upstream's configuration carries one, and copying a config that used it
53
+ * silently fell back to the built-in default instead — a cache with a
54
+ * different lifetime than the file says.
55
+ */
56
+ ttl?: Duration;
42
57
  /**
43
58
  * The stores this application can use, by name. Each is a {@link store}
44
59
  * builder — the shape a cache config takes — or the plain
@@ -183,6 +198,13 @@ export const drivers = {
183
198
  export class CacheStoreManager {
184
199
  #config: MultiStoreConfig;
185
200
  #built: Map<string, CacheManager> = new Map();
201
+ /**
202
+ * Whether the application has been readied.
203
+ *
204
+ * Stores are created on first use, so one first touched by a request is
205
+ * created AFTER `ready()` has run — and nothing would have connected it.
206
+ */
207
+ #connected = false;
186
208
  // Held here as well as on each store, so a listener registered before a
187
209
  // store is first used still reaches it.
188
210
  readonly #listeners: {
@@ -217,7 +239,8 @@ export class CacheStoreManager {
217
239
  const cfg = entryOf(declared);
218
240
  const manager = new CacheManager(cfg.driver(), {
219
241
  prefix: cfg.prefix,
220
- ttl: cfg.ttl,
242
+ // The store's own, or the one every store inherits.
243
+ ttl: cfg.ttl ?? this.#config.ttl,
221
244
  grace: cfg.grace,
222
245
  timeout: cfg.timeout,
223
246
  hardTimeout: cfg.hardTimeout,
@@ -238,7 +261,17 @@ export class CacheStoreManager {
238
261
  replay("cache:written");
239
262
  replay("cache:deleted");
240
263
  replay("cache:cleared");
264
+ // So `cache.use('other')` works on whichever store the provider
265
+ // published — upstream's manager is one object that both operates on
266
+ // the default store and reaches the named ones.
267
+ manager.belongsTo(this);
241
268
  this.#built.set(store, manager);
269
+ // Built after the application was readied: connect it now rather than
270
+ // leave it the only store on no bus. `use()` is synchronous — upstream's
271
+ // is too, and the README chains off it — so the manager's own
272
+ // operations wait for this, and its failure costs staleness rather than
273
+ // every read.
274
+ if (this.#connected) manager.connect().catch(() => {});
242
275
  return manager;
243
276
  }
244
277
 
@@ -295,7 +328,23 @@ export class CacheStoreManager {
295
328
  * Call it from a shutdown hook. A store on an INJECTED client leaves that
296
329
  * client alone — echo did not open it.
297
330
  */
331
+ /**
332
+ * Open what every BUILT store needs outside the process.
333
+ *
334
+ * Stores are created on first use, so this reaches the ones the
335
+ * application has actually asked for — naming a Redis store in an
336
+ * environment that runs on memory still opens nothing.
337
+ */
338
+ async connectAll(): Promise<void> {
339
+ // Set FIRST, so a store built while this is in flight connects itself
340
+ // rather than being missed by a walk that had already listed the built
341
+ // ones.
342
+ this.#connected = true;
343
+ await Promise.all([...this.#built.values()].map((m) => m.connect()));
344
+ }
345
+
298
346
  async disconnectAll(): Promise<void> {
347
+ this.#connected = false;
299
348
  await Promise.all([...this.#built.values()].map((m) => m.disconnect()));
300
349
  }
301
350
  }
@@ -208,9 +208,22 @@ export class MemoryDriver implements TaggableDriver {
208
208
  return this.#store.delete(key);
209
209
  }
210
210
 
211
- async flush(): Promise<void> {
212
- this.#store.clear();
213
- this.#tagIndex.clear();
211
+ async flush(prefix?: string): Promise<void> {
212
+ if (prefix === undefined) {
213
+ this.#store.clear();
214
+ this.#tagIndex.clear();
215
+ return;
216
+ }
217
+ for (const key of [...this.#store.keys()]) {
218
+ if (key.startsWith(prefix)) this.#store.delete(key);
219
+ }
220
+ // The tag index points at keys; the ones that are gone go with them.
221
+ for (const [tag, keys] of [...this.#tagIndex.entries()]) {
222
+ for (const key of [...keys]) {
223
+ if (key.startsWith(prefix)) keys.delete(key);
224
+ }
225
+ if (keys.size === 0) this.#tagIndex.delete(tag);
226
+ }
214
227
  }
215
228
 
216
229
  async has(key: string): Promise<boolean> {
@@ -220,16 +220,19 @@ export class RedisDriver implements TaggableDriver {
220
220
  await this.#applyTags(key, tags, physical);
221
221
  }
222
222
 
223
- async flush(): Promise<void> {
223
+ async flush(prefix?: string): Promise<void> {
224
224
  const client = await this.#client();
225
225
  const scan = client.scan;
226
226
  if (typeof scan === "function") {
227
+ // The driver's own prefix scopes it to this store; `prefix` scopes
228
+ // it further, to the namespace that asked.
229
+ const match = `${this.#prefix}${prefix ?? ""}`;
227
230
  let cursor = "0";
228
231
  do {
229
232
  const [nextCursor, keys] = await scan(
230
233
  cursor,
231
234
  "MATCH",
232
- `${this.#prefix}*`,
235
+ `${match}*`,
233
236
  "COUNT",
234
237
  100,
235
238
  );
@@ -19,6 +19,15 @@ import type {
19
19
  export interface BusMessage {
20
20
  type: "delete" | "clear";
21
21
  keys: string[];
22
+ /**
23
+ * Which subtree a `clear` covers. Absent means the whole store.
24
+ *
25
+ * A namespaced clear that told its peers "drop everything" threw away
26
+ * every other tenant's L1 entries on those instances — the same mistake
27
+ * as flushing locally, one hop away. A message from an older instance
28
+ * carries none, and is acted on as the whole-store clear it meant.
29
+ */
30
+ prefix?: string;
22
31
  /**
23
32
  * The tier that published it.
24
33
  *
@@ -41,7 +50,31 @@ export interface BusMessage {
41
50
  /** Duck-typed pub/sub bus for cross-instance L1 invalidation (e.g. Redis pub/sub). */
42
51
  export interface CacheBus {
43
52
  publish(message: BusMessage): void | Promise<void>;
44
- subscribe(handler: (message: BusMessage) => void): void;
53
+ /**
54
+ * Start listening for peer invalidations.
55
+ *
56
+ * AWAITED, and a rejection is an answer. A bus that reports its failure and
57
+ * resolves anyway — which is what a Redis client shared with the rest of
58
+ * the application does — left the tier believing it was subscribed while no
59
+ * handler was installed: every instance then served its own stale L1 until
60
+ * the TTL ran out, including for anything an application had cached about
61
+ * who may do what.
62
+ */
63
+ subscribe(handler: (message: BusMessage) => void): void | Promise<void>;
64
+ /**
65
+ * Stop listening — the HANDLER names which subscription, because a bus is
66
+ * shared: quasar keeps a `Set` per channel, so "drop everything here" would
67
+ * silence whatever else the application listens to on the connection the
68
+ * cache borrows.
69
+ *
70
+ * There was no way to stop at all, so every hot reload and every test left
71
+ * another handler on the bus: each holding an L1 nobody would read again,
72
+ * and each acting on invalidations meant for a driver that no longer
73
+ * exists. Optional, so a bus written against the old contract still works —
74
+ * it just leaks, and now that is the bus's omission rather than a gap in
75
+ * the contract.
76
+ */
77
+ unsubscribe?(handler: (message: BusMessage) => void): void | Promise<void>;
45
78
  }
46
79
 
47
80
  export interface TieredDriverOptions {
@@ -110,6 +143,8 @@ export class TieredDriver implements TaggableDriver {
110
143
  #l1: CacheDriver;
111
144
  #l2: CacheDriver;
112
145
  #bus: CacheBus | undefined;
146
+ /** The listener on the bus, kept so `disconnect` can name it again. */
147
+ #busHandler: ((message: BusMessage) => void) | undefined;
113
148
  /** This tier, as a bus sender. */
114
149
  readonly #id = crypto.randomUUID();
115
150
 
@@ -117,19 +152,56 @@ export class TieredDriver implements TaggableDriver {
117
152
  this.#l1 = options.l1;
118
153
  this.#l2 = options.l2;
119
154
  this.#bus = options.bus;
120
- this.#bus?.subscribe((message) => {
155
+ this.#onPeerMessage = (message: BusMessage): void => {
121
156
  // Our own invalidation, come back round the bus. Acting on it would
122
157
  // undo the write that sent it.
123
158
  if (message.senderId === this.#id) return;
124
159
  // Peer invalidation: only the local L1 needs clearing (L2 is shared).
125
160
  if (message.type === "clear") {
126
- this.#invalidate("flush", () => this.#l1.flush());
161
+ this.#invalidate("flush", () => this.#l1.flush(message.prefix));
127
162
  return;
128
163
  }
129
164
  for (const key of message.keys) {
130
165
  this.#invalidate(key, () => this.#l1.delete(key));
131
166
  }
132
- });
167
+ };
168
+ }
169
+
170
+ /** The listener this tier will install, built once in the constructor. */
171
+ readonly #onPeerMessage: (message: BusMessage) => void;
172
+ /** A subscribe in flight, so two callers do not open two. */
173
+ #connecting: Promise<void> | undefined;
174
+
175
+ /**
176
+ * Subscribe to the bus. Idempotent, and awaited by whoever readies the app.
177
+ *
178
+ * NOT done in the constructor: a store is built when the cache service is
179
+ * published, which happens while the application boots — including under an
180
+ * inspection that never shuts anything down. Opening the socket there left
181
+ * a subscriber behind every time someone listed the routes.
182
+ */
183
+ async connect(): Promise<void> {
184
+ if (!this.#bus || this.#busHandler) return;
185
+ // SINGLE-FLIGHT. Two callers — the provider readying and the first
186
+ // operation on a store built after that — both saw an empty handler
187
+ // before the first `await` resolved, so both subscribed and only one
188
+ // came off. `#busHandler` is set after the await, which is exactly the
189
+ // window; the promise closes it.
190
+ const bus = this.#bus;
191
+ this.#connecting ??= (async () => {
192
+ await bus.subscribe(this.#onPeerMessage);
193
+ // Recorded only once the bus has accepted it. Marked before, a
194
+ // failed subscribe left a handler this driver believed was
195
+ // installed and would later try to remove.
196
+ this.#busHandler = this.#onPeerMessage;
197
+ })();
198
+ try {
199
+ await this.#connecting;
200
+ } finally {
201
+ // Cleared either way: a failure must be retryable, and a success
202
+ // has `#busHandler` to say so.
203
+ this.#connecting = undefined;
204
+ }
133
205
  }
134
206
 
135
207
  /**
@@ -232,11 +304,19 @@ export class TieredDriver implements TaggableDriver {
232
304
  return l1.value || l2.value;
233
305
  }
234
306
 
235
- async flush(): Promise<void> {
236
- const l1 = await settle(() => this.#l1.flush());
237
- const l2 = await settle(() => this.#l2.flush());
307
+ async flush(prefix?: string): Promise<void> {
308
+ const l1 = await settle(() => this.#l1.flush(prefix));
309
+ const l2 = await settle(() => this.#l2.flush(prefix));
238
310
  if (l2.ok) {
239
- await this.#bus?.publish({ type: "clear", keys: [], senderId: this.#id });
311
+ // The prefix travels: a peer that flushed its WHOLE L1 on a
312
+ // namespaced clear would throw away every other tenant's entries
313
+ // on that instance, which is the same mistake one hop away.
314
+ await this.#bus?.publish({
315
+ type: "clear",
316
+ keys: [],
317
+ prefix,
318
+ senderId: this.#id,
319
+ });
240
320
  }
241
321
  if (!l1.ok) throw l1.error;
242
322
  if (!l2.ok) throw l2.error;
@@ -286,13 +366,30 @@ export class TieredDriver implements TaggableDriver {
286
366
  if (!l2.ok) throw l2.error;
287
367
  }
288
368
 
289
- /** Release both layers (bentocache `disconnect`). */
369
+ /** Release the bus and both layers (bentocache `disconnect`). */
290
370
  async disconnect(): Promise<void> {
291
- // Both are released even when the first refuses: a tier left connected
292
- // because its neighbour threw is a socket nobody closes.
371
+ // All three are released even when one refuses: a tier left connected
372
+ // because its neighbour threw is a socket nobody closes, and a listener
373
+ // left on the bus is an L1 nobody will read acting on invalidations for
374
+ // a driver that no longer exists.
375
+ // A subscribe still in flight finishes FIRST, so its listener is one this
376
+ // teardown can see. Reading the handler ahead of it saw none, did
377
+ // nothing, and the subscribe then installed a listener nothing was
378
+ // tracking any more.
379
+ if (this.#connecting) await this.#connecting.catch(() => {});
380
+ // Forgotten only once the bus has accepted its removal. Cleared first, a
381
+ // rejecting unsubscribe left a live listener nothing could name again —
382
+ // not to retry it, not to remove it at a second shutdown.
383
+ const handler = this.#busHandler;
384
+ const bus = await settle(async () => {
385
+ if (!handler) return;
386
+ await this.#bus?.unsubscribe?.(handler);
387
+ this.#busHandler = undefined;
388
+ });
293
389
  const l1 = await settle(async () => this.#l1.disconnect?.());
294
390
  const l2 = await settle(async () => this.#l2.disconnect?.());
295
391
  if (!l1.ok) throw l1.error;
296
392
  if (!l2.ok) throw l2.error;
393
+ if (!bus.ok) throw bus.error;
297
394
  }
298
395
  }