@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.
- package/dist/CacheManager.d.ts +52 -6
- package/dist/CacheManager.d.ts.map +1 -1
- package/dist/CacheManager.js +146 -6
- package/dist/CacheManager.js.map +1 -1
- package/dist/EchoProvider.d.ts +27 -1
- package/dist/EchoProvider.d.ts.map +1 -1
- package/dist/EchoProvider.js +31 -3
- package/dist/EchoProvider.js.map +1 -1
- package/dist/StoreManager.d.ts +25 -2
- package/dist/StoreManager.d.ts.map +1 -1
- package/dist/StoreManager.js +35 -1
- package/dist/StoreManager.js.map +1 -1
- package/dist/drivers/MemoryDriver.d.ts +1 -1
- package/dist/drivers/MemoryDriver.d.ts.map +1 -1
- package/dist/drivers/MemoryDriver.js +19 -3
- package/dist/drivers/MemoryDriver.js.map +1 -1
- package/dist/drivers/RedisDriver.d.ts +1 -1
- package/dist/drivers/RedisDriver.d.ts.map +1 -1
- package/dist/drivers/RedisDriver.js +5 -2
- package/dist/drivers/RedisDriver.js.map +1 -1
- package/dist/drivers/TieredDriver.d.ts +45 -3
- package/dist/drivers/TieredDriver.d.ts.map +1 -1
- package/dist/drivers/TieredDriver.js +77 -10
- package/dist/drivers/TieredDriver.js.map +1 -1
- package/dist/quasar.d.ts.map +1 -1
- package/dist/quasar.js +55 -11
- package/dist/quasar.js.map +1 -1
- package/dist/types.d.ts +26 -1
- package/dist/types.d.ts.map +1 -1
- package/package.json +10 -10
- package/src/CacheManager.ts +163 -12
- package/src/EchoProvider.ts +32 -3
- package/src/StoreManager.ts +52 -3
- package/src/drivers/MemoryDriver.ts +16 -3
- package/src/drivers/RedisDriver.ts +5 -2
- package/src/drivers/TieredDriver.ts +108 -11
- package/src/quasar.ts +81 -18
- 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
|
-
|
|
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.#
|
|
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
|
-
|
|
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
|
-
//
|
|
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(
|
|
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
|
-
|
|
148
|
-
|
|
149
|
-
|
|
150
|
-
|
|
151
|
-
|
|
152
|
-
|
|
153
|
-
|
|
154
|
-
|
|
155
|
-
|
|
156
|
-
|
|
157
|
-
|
|
158
|
-
|
|
159
|
-
|
|
160
|
-
|
|
161
|
-
|
|
162
|
-
|
|
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
|
-
|
|
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.
|