@c9up/echo 0.1.16 → 0.2.1

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 (38) 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.map +1 -1
  26. package/dist/quasar.js +55 -11
  27. package/dist/quasar.js.map +1 -1
  28. package/dist/types.d.ts +26 -1
  29. package/dist/types.d.ts.map +1 -1
  30. package/package.json +10 -10
  31. package/src/CacheManager.ts +163 -12
  32. package/src/EchoProvider.ts +32 -3
  33. package/src/StoreManager.ts +52 -3
  34. package/src/drivers/MemoryDriver.ts +16 -3
  35. package/src/drivers/RedisDriver.ts +5 -2
  36. package/src/drivers/TieredDriver.ts +108 -11
  37. package/src/quasar.ts +81 -18
  38. package/src/types.ts +26 -1
@@ -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
  }
package/src/quasar.ts CHANGED
@@ -68,7 +68,26 @@ function isConnectionSource(value: unknown): value is ConnectionSource {
68
68
  /** The slice of quasar's manager a pub/sub bus needs. */
69
69
  interface PubSubSource {
70
70
  publish(channel: string, message: string): unknown;
71
- subscribe(channel: string, handler: (message: string) => void): unknown;
71
+ subscribe(
72
+ channel: string,
73
+ handler: (message: string) => void,
74
+ /**
75
+ * How the outcome is REPORTED. Quasar catches the Redis error and calls
76
+ * `onError` rather than rejecting, and newer versions declare
77
+ * `subscribe` itself `void` — so the call's return value proves nothing
78
+ * either way, and these two are the whole signal.
79
+ */
80
+ options?: {
81
+ onSubscription?: (count: number) => void;
82
+ onError?: (error: unknown) => void;
83
+ },
84
+ ): unknown;
85
+ /**
86
+ * Optional, and NAMED when it is there: quasar stacks handlers per channel,
87
+ * so dropping them all would silence whatever else the application listens
88
+ * to on the connection echo borrows.
89
+ */
90
+ unsubscribe?(channel: string, handler?: (message: string) => void): unknown;
72
91
  }
73
92
 
74
93
  function isPubSubSource(value: unknown): value is PubSubSource {
@@ -120,6 +139,11 @@ export function quasarBus(options?: {
120
139
  }): CacheBus {
121
140
  const channel = options?.channel ?? "echo::invalidate";
122
141
  let ready: Promise<PubSubSource> | undefined;
142
+ /** Per subscriber, the wrapper actually registered — once it has been. */
143
+ const opened = new Map<
144
+ (message: BusMessage) => void,
145
+ Promise<(raw: string) => void>
146
+ >();
123
147
 
124
148
  const manager = (): Promise<PubSubSource> => {
125
149
  ready ??= loadQuasar(
@@ -143,24 +167,63 @@ export function quasarBus(options?: {
143
167
  const source = await manager();
144
168
  await source.publish(channel, JSON.stringify(message));
145
169
  },
146
- subscribe(handler: (message: BusMessage) => void): void {
147
- // Not awaited: `subscribe` is synchronous in the bus contract, and the
148
- // socket opens on quasar's own schedule. A failure to reach Redis must
149
- // not take down the store — a bus that is down costs staleness, and
150
- // throwing here would cost every cache read.
151
- void manager()
152
- .then((source) =>
153
- source.subscribe(channel, (raw: string) => {
154
- try {
155
- handler(JSON.parse(raw) as BusMessage);
156
- } catch {
157
- /* a malformed frame is not a reason to stop listening */
158
- }
159
- }),
160
- )
161
- .catch(() => {
162
- /* reported by the first publish, which does surface its error */
170
+ async subscribe(handler: (message: BusMessage) => void): Promise<void> {
171
+ const wrapper = (raw: string): void => {
172
+ try {
173
+ handler(JSON.parse(raw) as BusMessage);
174
+ } catch {
175
+ /* a malformed frame is not a reason to stop listening */
176
+ }
177
+ };
178
+ // AWAITED, and a reported failure becomes a rejection.
179
+ //
180
+ // This used to be fire-and-forget with the rejection swallowed, and
181
+ // quasar catches the Redis error itself and resolves — so the tier
182
+ // believed it was subscribed while no handler was installed. Every
183
+ // instance then served its own stale L1 until the TTL ran out, with
184
+ // nothing anywhere to say the bus was down.
185
+ //
186
+ // The provider awaits this in `ready()`, so an unreachable bus is a
187
+ // failed boot rather than a deployment that looks healthy and is
188
+ // quietly incoherent.
189
+ const attempt = (async (): Promise<(raw: string) => void> => {
190
+ const source = await manager();
191
+ // Waited on through the callbacks, not on the call's return value:
192
+ // `subscribe` reports a failure rather than rejecting, and newer
193
+ // quasar declares it `void`. This shape is correct against both.
194
+ await new Promise<void>((resolve, reject) => {
195
+ source.subscribe(channel, wrapper, {
196
+ onSubscription: () => resolve(),
197
+ onError: (error) => {
198
+ opened.delete(handler);
199
+ reject(error instanceof Error ? error : new Error(String(error)));
200
+ },
201
+ });
163
202
  });
203
+ return wrapper;
204
+ })();
205
+ opened.set(handler, attempt);
206
+ // Forgotten on a direct rejection too, so a retry is not refused by
207
+ // bookkeeping for a subscription that never happened.
208
+ attempt.catch(() => opened.delete(handler));
209
+ await attempt;
210
+ },
211
+ async unsubscribe(handler: (message: BusMessage) => void): Promise<void> {
212
+ // The subscribe may still be opening the socket. Removing ahead of it
213
+ // takes nothing off and leaves the handler to land afterwards, on a
214
+ // bus nobody is tracking any more.
215
+ const pending = opened.get(handler);
216
+ if (pending === undefined) return;
217
+ const wrapper = await pending;
218
+ const source = await manager();
219
+ // NAMED. Quasar keeps a `Set` of handlers per channel, so an unnamed
220
+ // unsubscribe drops every listener on a connection the application
221
+ // shares with the cache.
222
+ await source.unsubscribe?.(channel, wrapper);
223
+ // Forgotten LAST. Dropped before the call, a refusal left a live
224
+ // listener nothing could name again — neither to retry it nor to
225
+ // remove it at a second shutdown.
226
+ opened.delete(handler);
164
227
  },
165
228
  };
166
229
  }
package/src/types.ts CHANGED
@@ -53,7 +53,19 @@ export interface CacheDriver {
53
53
  get<T = unknown>(key: string): Promise<T | null>;
54
54
  set(key: string, value: unknown, ttlSeconds?: number): Promise<void>;
55
55
  delete(key: string): Promise<boolean>;
56
- flush(): Promise<void>;
56
+ /**
57
+ * Remove everything — or, when `prefix` is given, only the keys under it.
58
+ *
59
+ * A namespaced view shares this driver, so a `clear()` on one had to be
60
+ * able to say WHICH subtree it meant. Without that it flushed the whole
61
+ * store, and a namespace per tenant is the documented use: one tenant
62
+ * clearing its own cache emptied everyone else's.
63
+ *
64
+ * A driver that cannot scope the removal must REFUSE when a prefix is
65
+ * given. Flushing everything instead is the failure this parameter exists
66
+ * to prevent, and it is silent.
67
+ */
68
+ flush(prefix?: string): Promise<void>;
57
69
  has(key: string): Promise<boolean>;
58
70
  /** Grace-aware read: returns the entry even if stale, or `null` if physically gone. */
59
71
  getEntry?<T = unknown>(key: string): Promise<CacheEntry<T> | null>;
@@ -63,6 +75,19 @@ export interface CacheDriver {
63
75
  value: unknown,
64
76
  options: DriverSetOptions,
65
77
  ): Promise<void>;
78
+ /**
79
+ * Open whatever this driver needs OUTSIDE the process — a bus subscription,
80
+ * a connection it owns.
81
+ *
82
+ * Separate from the constructor on purpose. Building a store is what
83
+ * publishing the cache service does, and that happens while the application
84
+ * boots, including under `ream inspect` — which never shuts anything down.
85
+ * A driver that opened a socket to exist left one behind every time someone
86
+ * listed the routes. This is called once the application is ready, and its
87
+ * failure is the application's to refuse: a tiered store that never
88
+ * subscribed serves stale L1 copies to everyone until their TTL.
89
+ */
90
+ connect?(): Promise<void>;
66
91
  /**
67
92
  * Drop entries this driver knows to be expired (bentocache `prune`). Only
68
93
  * stores that do not evict on their own need it.