@c9up/echo 0.2.2 → 0.2.4
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 +2 -0
- package/dist/CacheManager.d.ts.map +1 -1
- package/dist/CacheManager.js +92 -32
- package/dist/CacheManager.js.map +1 -1
- package/dist/EchoProvider.d.ts.map +1 -1
- package/dist/EchoProvider.js +32 -3
- package/dist/EchoProvider.js.map +1 -1
- package/dist/StoreManager.d.ts +28 -9
- package/dist/StoreManager.d.ts.map +1 -1
- package/dist/StoreManager.js +42 -18
- package/dist/StoreManager.js.map +1 -1
- package/dist/bytes.d.ts +13 -0
- package/dist/bytes.d.ts.map +1 -0
- package/dist/bytes.js +35 -0
- package/dist/bytes.js.map +1 -0
- package/dist/claim.d.ts +15 -0
- package/dist/claim.d.ts.map +1 -0
- package/dist/claim.js +10 -0
- package/dist/claim.js.map +1 -0
- package/dist/configure.d.ts +7 -0
- package/dist/configure.d.ts.map +1 -1
- package/dist/configure.js +5 -18
- package/dist/configure.js.map +1 -1
- package/dist/console/cacheClear.d.ts +13 -0
- package/dist/console/cacheClear.d.ts.map +1 -0
- package/dist/console/cacheClear.js +69 -0
- package/dist/console/cacheClear.js.map +1 -0
- package/dist/console/cacheDelete.d.ts +11 -0
- package/dist/console/cacheDelete.d.ts.map +1 -0
- package/dist/console/cacheDelete.js +42 -0
- package/dist/console/cacheDelete.js.map +1 -0
- package/dist/console/cachePrune.d.ts +9 -0
- package/dist/console/cachePrune.d.ts.map +1 -0
- package/dist/console/cachePrune.js +35 -0
- package/dist/console/cachePrune.js.map +1 -0
- package/dist/console/contract.d.ts +64 -0
- package/dist/console/contract.d.ts.map +1 -0
- package/dist/console/contract.js +32 -0
- package/dist/console/contract.js.map +1 -0
- package/dist/console/index.d.ts +25 -0
- package/dist/console/index.d.ts.map +1 -0
- package/dist/console/index.js +38 -0
- package/dist/console/index.js.map +1 -0
- package/dist/console/store.d.ts +14 -0
- package/dist/console/store.d.ts.map +1 -0
- package/dist/console/store.js +35 -0
- package/dist/console/store.js.map +1 -0
- package/dist/drivers/MemoryDriver.d.ts +36 -1
- package/dist/drivers/MemoryDriver.d.ts.map +1 -1
- package/dist/drivers/MemoryDriver.js +157 -62
- package/dist/drivers/MemoryDriver.js.map +1 -1
- package/dist/drivers/RedisDriver.d.ts +13 -8
- package/dist/drivers/RedisDriver.d.ts.map +1 -1
- package/dist/drivers/RedisDriver.js +171 -94
- package/dist/drivers/RedisDriver.js.map +1 -1
- package/dist/drivers/TieredDriver.d.ts +42 -0
- package/dist/drivers/TieredDriver.d.ts.map +1 -1
- package/dist/drivers/TieredDriver.js +114 -9
- package/dist/drivers/TieredDriver.js.map +1 -1
- package/dist/duration.d.ts +13 -3
- package/dist/duration.d.ts.map +1 -1
- package/dist/duration.js +22 -7
- package/dist/duration.js.map +1 -1
- package/dist/errors.d.ts +60 -2
- package/dist/errors.d.ts.map +1 -1
- package/dist/errors.js +81 -6
- package/dist/errors.js.map +1 -1
- package/dist/index.d.ts +4 -4
- package/dist/index.d.ts.map +1 -1
- package/dist/index.js +3 -3
- package/dist/index.js.map +1 -1
- package/dist/quasar.d.ts +1 -1
- package/dist/quasar.d.ts.map +1 -1
- package/dist/quasar.js +27 -6
- package/dist/quasar.js.map +1 -1
- package/dist/services/main.d.ts +1 -1
- package/dist/services/main.d.ts.map +1 -1
- package/dist/services/main.js +22 -5
- package/dist/services/main.js.map +1 -1
- package/dist/stubs.d.ts +14 -0
- package/dist/stubs.d.ts.map +1 -0
- package/dist/stubs.js +15 -0
- package/dist/stubs.js.map +1 -0
- package/dist/types.d.ts +12 -1
- package/dist/types.d.ts.map +1 -1
- package/dist/vendor/quasarConnection.d.ts +26 -3
- package/dist/vendor/quasarConnection.d.ts.map +1 -1
- package/dist/vendor/quasarConnection.js +44 -23
- package/dist/vendor/quasarConnection.js.map +1 -1
- package/package.json +8 -3
- package/src/CacheManager.ts +117 -41
- package/src/EchoProvider.ts +45 -4
- package/src/StoreManager.ts +86 -31
- package/src/bytes.ts +38 -0
- package/src/claim.ts +22 -0
- package/src/configure.ts +13 -21
- package/src/console/cacheClear.ts +96 -0
- package/src/console/cacheDelete.ts +65 -0
- package/src/console/cachePrune.ts +57 -0
- package/src/console/contract.ts +93 -0
- package/src/console/index.ts +61 -0
- package/src/console/store.ts +47 -0
- package/src/drivers/MemoryDriver.ts +205 -60
- package/src/drivers/RedisDriver.ts +205 -101
- package/src/drivers/TieredDriver.ts +169 -9
- package/src/duration.ts +28 -7
- package/src/errors.ts +103 -6
- package/src/index.ts +17 -3
- package/src/quasar.ts +44 -8
- package/src/services/main.ts +26 -8
- package/src/stubs.ts +16 -0
- package/src/types.ts +13 -2
- package/src/vendor/quasarConnection.ts +84 -22
- package/stubs/config/cache.stub +21 -0
|
@@ -8,6 +8,8 @@
|
|
|
8
8
|
* shared, so only L1 needs cross-instance invalidation.
|
|
9
9
|
*/
|
|
10
10
|
|
|
11
|
+
import { type Duration, resolveTtlSeconds } from "../duration.js";
|
|
12
|
+
import { EchoError, L2CacheError } from "../errors.js";
|
|
11
13
|
import type {
|
|
12
14
|
CacheDriver,
|
|
13
15
|
CacheEntry,
|
|
@@ -45,6 +47,40 @@ export interface BusMessage {
|
|
|
45
47
|
* already did.
|
|
46
48
|
*/
|
|
47
49
|
senderId?: string;
|
|
50
|
+
/**
|
|
51
|
+
* The store that published it. Several stores — and several applications
|
|
52
|
+
* — can share one channel, and a message carried no store: one store's
|
|
53
|
+
* write dropped another store's L1 copy of the same key, and its
|
|
54
|
+
* deleteByTag flushed every other store's L1. A tier with a store name
|
|
55
|
+
* acts only on messages carrying the same one, as upstream drops messages
|
|
56
|
+
* for caches it does not manage.
|
|
57
|
+
*/
|
|
58
|
+
store?: string;
|
|
59
|
+
}
|
|
60
|
+
|
|
61
|
+
/**
|
|
62
|
+
* Whether a received frame is an invalidation message, field by field.
|
|
63
|
+
*
|
|
64
|
+
* A bus hands over whatever arrived on the channel. Trusted as is, a string
|
|
65
|
+
* `keys` was iterated character by character, any unknown `type` read as a
|
|
66
|
+
* delete, and a missing `keys` threw inside the handler.
|
|
67
|
+
*/
|
|
68
|
+
export function isBusMessage(value: unknown): value is BusMessage {
|
|
69
|
+
if (typeof value !== "object" || value === null) return false;
|
|
70
|
+
const type = Reflect.get(value, "type");
|
|
71
|
+
const keys = Reflect.get(value, "keys");
|
|
72
|
+
const optional = (name: string): boolean => {
|
|
73
|
+
const field = Reflect.get(value, name);
|
|
74
|
+
return field === undefined || typeof field === "string";
|
|
75
|
+
};
|
|
76
|
+
return (
|
|
77
|
+
(type === "delete" || type === "clear") &&
|
|
78
|
+
Array.isArray(keys) &&
|
|
79
|
+
keys.every((key) => typeof key === "string") &&
|
|
80
|
+
optional("prefix") &&
|
|
81
|
+
optional("senderId") &&
|
|
82
|
+
optional("store")
|
|
83
|
+
);
|
|
48
84
|
}
|
|
49
85
|
|
|
50
86
|
/** Duck-typed pub/sub bus for cross-instance L1 invalidation (e.g. Redis pub/sub). */
|
|
@@ -81,6 +117,30 @@ export interface TieredDriverOptions {
|
|
|
81
117
|
l1: CacheDriver;
|
|
82
118
|
l2: CacheDriver;
|
|
83
119
|
bus?: CacheBus;
|
|
120
|
+
/**
|
|
121
|
+
* Treat a failed L2 read as a miss and a failed L2 write as skipped,
|
|
122
|
+
* rather than failing the call (upstream `suppressL2Errors`). Default
|
|
123
|
+
* `true`: there is an L1 to serve from, so a Redis outage costs hit rate,
|
|
124
|
+
* not every request. `false` surfaces each failure as an
|
|
125
|
+
* {@link L2CacheError}.
|
|
126
|
+
*
|
|
127
|
+
* Invalidations — `delete`, `flush`, `deleteByTag` — report a failed L2
|
|
128
|
+
* either way: a removal that did not reach the shared tier leaves the
|
|
129
|
+
* value served to every other instance, and the caller has to know.
|
|
130
|
+
*/
|
|
131
|
+
suppressL2Errors?: boolean;
|
|
132
|
+
/**
|
|
133
|
+
* After an L2 failure, skip the L2 for this long instead of waiting on a
|
|
134
|
+
* dead server for every call (upstream `l2CircuitBreakerDuration`).
|
|
135
|
+
* Off by default.
|
|
136
|
+
*/
|
|
137
|
+
l2CircuitBreakerDuration?: Duration;
|
|
138
|
+
/**
|
|
139
|
+
* The store this tier belongs to, stamped on what it publishes and
|
|
140
|
+
* required on what it acts on. Set by the store manager from the config
|
|
141
|
+
* key; a tier without one acts on every well-formed message.
|
|
142
|
+
*/
|
|
143
|
+
store?: string;
|
|
84
144
|
}
|
|
85
145
|
|
|
86
146
|
function isTaggable(driver: CacheDriver): driver is TaggableDriver {
|
|
@@ -148,14 +208,32 @@ export class TieredDriver implements TaggableDriver {
|
|
|
148
208
|
/** This tier, as a bus sender. */
|
|
149
209
|
readonly #id = crypto.randomUUID();
|
|
150
210
|
|
|
211
|
+
readonly #store: string | undefined;
|
|
212
|
+
readonly #suppressL2Errors: boolean;
|
|
213
|
+
/** How long the breaker stays open after an L2 failure; `0` for no breaker. */
|
|
214
|
+
readonly #breakerMs: number;
|
|
215
|
+
/** Until when (epoch ms) the L2 is skipped. */
|
|
216
|
+
#breakerUntil = 0;
|
|
217
|
+
/** Whether the last L2 call failed — so an outage is reported once, not per call. */
|
|
218
|
+
#l2Failing = false;
|
|
219
|
+
|
|
151
220
|
constructor(options: TieredDriverOptions) {
|
|
152
221
|
this.#l1 = options.l1;
|
|
153
222
|
this.#l2 = options.l2;
|
|
154
223
|
this.#bus = options.bus;
|
|
224
|
+
this.#suppressL2Errors = options.suppressL2Errors ?? true;
|
|
225
|
+
this.#breakerMs =
|
|
226
|
+
Math.max(0, resolveTtlSeconds(options.l2CircuitBreakerDuration, 0)) *
|
|
227
|
+
1000;
|
|
228
|
+
this.#store = options.store;
|
|
155
229
|
this.#onPeerMessage = (message: BusMessage): void => {
|
|
230
|
+
// Checked here and not only in the transport: a custom bus hands
|
|
231
|
+
// over whatever it received.
|
|
232
|
+
if (!isBusMessage(message)) return;
|
|
156
233
|
// Our own invalidation, come back round the bus. Acting on it would
|
|
157
234
|
// undo the write that sent it.
|
|
158
235
|
if (message.senderId === this.#id) return;
|
|
236
|
+
if (this.#store !== undefined && message.store !== this.#store) return;
|
|
159
237
|
// Peer invalidation: only the local L1 needs clearing (L2 is shared).
|
|
160
238
|
if (message.type === "clear") {
|
|
161
239
|
this.#invalidate("flush", () => this.#l1.flush(message.prefix));
|
|
@@ -226,11 +304,70 @@ export class TieredDriver implements TaggableDriver {
|
|
|
226
304
|
});
|
|
227
305
|
}
|
|
228
306
|
|
|
307
|
+
/**
|
|
308
|
+
* Run a read or write against L2, the way upstream's remote cache does:
|
|
309
|
+
* skipped while the breaker is open, and on failure either answered by
|
|
310
|
+
* `fallback` (suppressed) or raised as an {@link L2CacheError}.
|
|
311
|
+
*/
|
|
312
|
+
async #onL2<T>(
|
|
313
|
+
operation: string,
|
|
314
|
+
run: () => Promise<T>,
|
|
315
|
+
fallback: T,
|
|
316
|
+
): Promise<{ ok: true; value: T } | { ok: false; value: T }> {
|
|
317
|
+
if (Date.now() < this.#breakerUntil) return { ok: false, value: fallback };
|
|
318
|
+
try {
|
|
319
|
+
const value = await run();
|
|
320
|
+
this.#l2Failing = false;
|
|
321
|
+
return { ok: true, value };
|
|
322
|
+
} catch (error) {
|
|
323
|
+
this.#l2Failed(operation, error);
|
|
324
|
+
if (this.#suppressL2Errors) return { ok: false, value: fallback };
|
|
325
|
+
throw new L2CacheError(operation, error);
|
|
326
|
+
}
|
|
327
|
+
}
|
|
328
|
+
|
|
329
|
+
/** Open the breaker, and report the outage when it starts. */
|
|
330
|
+
#l2Failed(operation: string, error: unknown): void {
|
|
331
|
+
if (this.#breakerMs > 0) this.#breakerUntil = Date.now() + this.#breakerMs;
|
|
332
|
+
if (this.#l2Failing) return;
|
|
333
|
+
this.#l2Failing = true;
|
|
334
|
+
process.stderr.write(
|
|
335
|
+
`[echo] tiered L2 ${operation} failed; serving from L1 until it answers again: ${
|
|
336
|
+
error instanceof Error ? error.message : String(error)
|
|
337
|
+
}\n`,
|
|
338
|
+
);
|
|
339
|
+
}
|
|
340
|
+
|
|
341
|
+
/**
|
|
342
|
+
* Run an invalidation against L2. Never suppressed and never skipped by
|
|
343
|
+
* the breaker: a removal that did not reach the shared tier leaves the
|
|
344
|
+
* value there for every other instance. NAMED DEVIATION — upstream
|
|
345
|
+
* suppresses these too; reporting them is the safer side.
|
|
346
|
+
*/
|
|
347
|
+
async #invalidateL2<T>(
|
|
348
|
+
operation: string,
|
|
349
|
+
run: () => Promise<T>,
|
|
350
|
+
): Promise<{ ok: true; value: T } | { ok: false; error: unknown }> {
|
|
351
|
+
try {
|
|
352
|
+
const value = await run();
|
|
353
|
+
this.#l2Failing = false;
|
|
354
|
+
return { ok: true, value };
|
|
355
|
+
} catch (error) {
|
|
356
|
+
this.#l2Failed(operation, error);
|
|
357
|
+
return { ok: false, error: new L2CacheError(operation, error) };
|
|
358
|
+
}
|
|
359
|
+
}
|
|
360
|
+
|
|
229
361
|
async getEntry<T = unknown>(key: string): Promise<CacheEntry<T> | null> {
|
|
230
362
|
const l1 = await readEntry<T>(this.#l1, key);
|
|
231
363
|
if (l1 && !l1.stale) return l1;
|
|
232
364
|
|
|
233
|
-
|
|
365
|
+
// A failed L2 read is a miss: the stale L1 copy, if any, still serves.
|
|
366
|
+
const { value: l2 } = await this.#onL2(
|
|
367
|
+
"read",
|
|
368
|
+
() => readEntry<T>(this.#l2, key),
|
|
369
|
+
null,
|
|
370
|
+
);
|
|
234
371
|
if (l2 && !l2.stale) {
|
|
235
372
|
// Promote a fresh L2 hit into L1 — preserving the remaining logical TTL
|
|
236
373
|
// so L1 cannot outlive L2 (a promotion with no TTL left an immortal L1
|
|
@@ -240,7 +377,10 @@ export class TieredDriver implements TaggableDriver {
|
|
|
240
377
|
// immortal L1 copy; skip promotion rather than cache it forever.
|
|
241
378
|
return l2;
|
|
242
379
|
}
|
|
243
|
-
|
|
380
|
+
// With its tags: a copy promoted without them was invisible to
|
|
381
|
+
// deleteByTag on this very instance, which skips its own bus
|
|
382
|
+
// message — so a revoked entry kept being served from here.
|
|
383
|
+
const opts: DriverSetOptions = l2.tags ? { tags: l2.tags } : {};
|
|
244
384
|
if (l2.expiresAt > 0) {
|
|
245
385
|
const remainingSeconds = (l2.expiresAt - Date.now()) / 1000;
|
|
246
386
|
// Raced past expiry between the stale check and now — don't promote
|
|
@@ -273,16 +413,26 @@ export class TieredDriver implements TaggableDriver {
|
|
|
273
413
|
options: DriverSetOptions,
|
|
274
414
|
): Promise<void> {
|
|
275
415
|
const l1 = await settle(() => writeEntry(this.#l1, key, value, options));
|
|
276
|
-
const l2 = await settle(() =>
|
|
416
|
+
const l2 = await settle(() =>
|
|
417
|
+
this.#onL2(
|
|
418
|
+
"write",
|
|
419
|
+
async () => {
|
|
420
|
+
await writeEntry(this.#l2, key, value, options);
|
|
421
|
+
return true;
|
|
422
|
+
},
|
|
423
|
+
false,
|
|
424
|
+
),
|
|
425
|
+
);
|
|
277
426
|
// Peers are told only when the shared write landed. Telling them to drop
|
|
278
427
|
// their L1 for a value that never reached L2 sends every one of them to a
|
|
279
428
|
// tier that does not have it. Upstream gates the same publish on the same
|
|
280
429
|
// thing (`if (this.l2 && l2Success || !this.l2)`).
|
|
281
|
-
if (l2.ok) {
|
|
430
|
+
if (l2.ok && l2.value.ok) {
|
|
282
431
|
await this.#bus?.publish({
|
|
283
432
|
type: "delete",
|
|
284
433
|
keys: [key],
|
|
285
434
|
senderId: this.#id,
|
|
435
|
+
store: this.#store,
|
|
286
436
|
});
|
|
287
437
|
}
|
|
288
438
|
if (!l1.ok) throw l1.error;
|
|
@@ -291,12 +441,13 @@ export class TieredDriver implements TaggableDriver {
|
|
|
291
441
|
|
|
292
442
|
async delete(key: string): Promise<boolean> {
|
|
293
443
|
const l1 = await settle(() => this.#l1.delete(key));
|
|
294
|
-
const l2 = await
|
|
444
|
+
const l2 = await this.#invalidateL2("delete", () => this.#l2.delete(key));
|
|
295
445
|
if (l2.ok) {
|
|
296
446
|
await this.#bus?.publish({
|
|
297
447
|
type: "delete",
|
|
298
448
|
keys: [key],
|
|
299
449
|
senderId: this.#id,
|
|
450
|
+
store: this.#store,
|
|
300
451
|
});
|
|
301
452
|
}
|
|
302
453
|
if (!l1.ok) throw l1.error;
|
|
@@ -306,7 +457,7 @@ export class TieredDriver implements TaggableDriver {
|
|
|
306
457
|
|
|
307
458
|
async flush(prefix?: string): Promise<void> {
|
|
308
459
|
const l1 = await settle(() => this.#l1.flush(prefix));
|
|
309
|
-
const l2 = await
|
|
460
|
+
const l2 = await this.#invalidateL2("flush", () => this.#l2.flush(prefix));
|
|
310
461
|
if (l2.ok) {
|
|
311
462
|
// The prefix travels: a peer that flushed its WHOLE L1 on a
|
|
312
463
|
// namespaced clear would throw away every other tenant's entries
|
|
@@ -316,6 +467,7 @@ export class TieredDriver implements TaggableDriver {
|
|
|
316
467
|
keys: [],
|
|
317
468
|
prefix,
|
|
318
469
|
senderId: this.#id,
|
|
470
|
+
store: this.#store,
|
|
319
471
|
});
|
|
320
472
|
}
|
|
321
473
|
if (!l1.ok) throw l1.error;
|
|
@@ -339,16 +491,24 @@ export class TieredDriver implements TaggableDriver {
|
|
|
339
491
|
const l1 = this.#l1;
|
|
340
492
|
const l2 = this.#l2;
|
|
341
493
|
if (!isTaggable(l1) || !isTaggable(l2)) {
|
|
342
|
-
throw new
|
|
494
|
+
throw new EchoError(
|
|
495
|
+
"E_ECHO_NOT_TAGGABLE",
|
|
343
496
|
"Echo: TieredDriver.deleteByTag requires both tiers to be taggable",
|
|
344
497
|
);
|
|
345
498
|
}
|
|
346
499
|
const local = await settle(() => l1.deleteByTag(tags));
|
|
347
|
-
const shared = await
|
|
500
|
+
const shared = await this.#invalidateL2("deleteByTag", () =>
|
|
501
|
+
l2.deleteByTag(tags),
|
|
502
|
+
);
|
|
348
503
|
// Peers can't map tags → keys locally; broadcast a clear so their L1 drops
|
|
349
504
|
// any tagged copies (conservative but correct).
|
|
350
505
|
if (shared.ok) {
|
|
351
|
-
await this.#bus?.publish({
|
|
506
|
+
await this.#bus?.publish({
|
|
507
|
+
type: "clear",
|
|
508
|
+
keys: [],
|
|
509
|
+
senderId: this.#id,
|
|
510
|
+
store: this.#store,
|
|
511
|
+
});
|
|
352
512
|
}
|
|
353
513
|
if (!local.ok) throw local.error;
|
|
354
514
|
if (!shared.ok) throw shared.error;
|
package/src/duration.ts
CHANGED
|
@@ -47,6 +47,8 @@ const UNIT_SECONDS: Record<string, number> = {
|
|
|
47
47
|
weeks: 604_800,
|
|
48
48
|
};
|
|
49
49
|
|
|
50
|
+
import { InvalidDurationError } from "./errors.js";
|
|
51
|
+
|
|
50
52
|
const DURATION_RE = /^\s*(-?\d+(?:\.\d+)?)\s*([a-z]+)?\s*$/i;
|
|
51
53
|
|
|
52
54
|
/**
|
|
@@ -56,14 +58,16 @@ const DURATION_RE = /^\s*(-?\d+(?:\.\d+)?)\s*([a-z]+)?\s*$/i;
|
|
|
56
58
|
export function parseDuration(value: string): number {
|
|
57
59
|
const match = DURATION_RE.exec(value);
|
|
58
60
|
if (!match) {
|
|
59
|
-
throw new
|
|
61
|
+
throw new InvalidDurationError(`Echo: invalid duration string "${value}"`);
|
|
60
62
|
}
|
|
61
63
|
const amount = Number(match[1]);
|
|
62
64
|
const unit = match[2]?.toLowerCase();
|
|
63
65
|
if (unit === undefined) return amount;
|
|
64
66
|
const factor = UNIT_SECONDS[unit];
|
|
65
67
|
if (factor === undefined) {
|
|
66
|
-
throw new
|
|
68
|
+
throw new InvalidDurationError(
|
|
69
|
+
`Echo: unknown duration unit "${unit}" in "${value}"`,
|
|
70
|
+
);
|
|
67
71
|
}
|
|
68
72
|
return amount * factor;
|
|
69
73
|
}
|
|
@@ -71,9 +75,12 @@ export function parseDuration(value: string): number {
|
|
|
71
75
|
/**
|
|
72
76
|
* Resolve a {@link Duration} to a TTL in **seconds**.
|
|
73
77
|
*
|
|
74
|
-
* @returns the TTL in seconds
|
|
75
|
-
* `null`, or
|
|
76
|
-
*
|
|
78
|
+
* @returns the TTL in seconds. `0` means "never expires" — an explicit
|
|
79
|
+
* `null`, a `0` or `Infinity`. A NEGATIVE result is kept negative: a TTL in
|
|
80
|
+
* the past means already expired, and the writers drop the entry rather
|
|
81
|
+
* than store it. It used to map to `0`, so a TTL computed from data — a
|
|
82
|
+
* token that had already expired — cached its value forever.
|
|
83
|
+
* @throws {InvalidDurationError} for NaN, which means nothing at all.
|
|
77
84
|
*/
|
|
78
85
|
export function resolveTtlSeconds(
|
|
79
86
|
ttl: Duration | undefined,
|
|
@@ -81,6 +88,20 @@ export function resolveTtlSeconds(
|
|
|
81
88
|
): number {
|
|
82
89
|
if (ttl === null) return 0;
|
|
83
90
|
if (ttl === undefined) return defaultSeconds;
|
|
84
|
-
|
|
85
|
-
|
|
91
|
+
return checkTtlSeconds(typeof ttl === "number" ? ttl : parseDuration(ttl));
|
|
92
|
+
}
|
|
93
|
+
|
|
94
|
+
/**
|
|
95
|
+
* The driver-level reading of a TTL in seconds: `undefined`, `0` and
|
|
96
|
+
* `Infinity` never expire, a negative one has already expired, NaN is
|
|
97
|
+
* refused. Shared by the manager and the drivers, so a driver called directly
|
|
98
|
+
* cannot turn a NaN into an entry that never expires either.
|
|
99
|
+
*/
|
|
100
|
+
export function checkTtlSeconds(seconds: number): number {
|
|
101
|
+
if (Number.isNaN(seconds)) {
|
|
102
|
+
throw new InvalidDurationError(
|
|
103
|
+
"Echo: a TTL of NaN is not a duration — pass a number of seconds, a string like '5m', or null for no expiry",
|
|
104
|
+
);
|
|
105
|
+
}
|
|
106
|
+
return seconds === Number.POSITIVE_INFINITY ? 0 : seconds;
|
|
86
107
|
}
|
package/src/errors.ts
CHANGED
|
@@ -1,12 +1,78 @@
|
|
|
1
1
|
/**
|
|
2
2
|
* Echo cache errors — bentocache parity (`errors.ts`).
|
|
3
|
+
*
|
|
4
|
+
* Every error carries a `code`. Upstream's are kept verbatim
|
|
5
|
+
* (`E_FACTORY_ERROR`, `E_FACTORY_HARD_TIMEOUT`, `E_UNDEFINED_VALUE`,
|
|
6
|
+
* `E_L2_CACHE_ERROR`): code written against a cache module already catches on
|
|
7
|
+
* them. Failures echo invents carry the `E_ECHO_` namespace.
|
|
3
8
|
*/
|
|
4
9
|
|
|
10
|
+
/**
|
|
11
|
+
* Base class for the errors echo raises with a code of its own, so a caller
|
|
12
|
+
* can match on `error.code`.
|
|
13
|
+
*/
|
|
14
|
+
export class EchoError extends Error {
|
|
15
|
+
readonly code: string;
|
|
16
|
+
|
|
17
|
+
constructor(code: string, message: string, options?: ErrorOptions) {
|
|
18
|
+
super(message, options);
|
|
19
|
+
this.name = new.target.name;
|
|
20
|
+
this.code = code;
|
|
21
|
+
}
|
|
22
|
+
}
|
|
23
|
+
|
|
24
|
+
/**
|
|
25
|
+
* Raised for a duration that cannot mean anything: NaN, or a string the
|
|
26
|
+
* parser does not read. A `TypeError`, as the parser's refusals always were.
|
|
27
|
+
*/
|
|
28
|
+
export class InvalidDurationError extends TypeError {
|
|
29
|
+
readonly code = "E_ECHO_INVALID_DURATION";
|
|
30
|
+
|
|
31
|
+
constructor(message: string) {
|
|
32
|
+
super(message);
|
|
33
|
+
this.name = "InvalidDurationError";
|
|
34
|
+
}
|
|
35
|
+
}
|
|
36
|
+
|
|
37
|
+
/**
|
|
38
|
+
* Raised when a caller waited `lockTimeout` on another caller's factory for
|
|
39
|
+
* the same key, had no stale value to fall back on, and gave up.
|
|
40
|
+
*/
|
|
41
|
+
export class LockTimeoutError extends EchoError {
|
|
42
|
+
/** The cache key whose lock was not obtained. */
|
|
43
|
+
readonly key: string;
|
|
44
|
+
|
|
45
|
+
constructor(key: string, timeoutMs: number) {
|
|
46
|
+
super(
|
|
47
|
+
"E_ECHO_LOCK_TIMEOUT",
|
|
48
|
+
`Echo: waited ${timeoutMs}ms for another caller's factory for "${key}" and gave up`,
|
|
49
|
+
);
|
|
50
|
+
this.key = key;
|
|
51
|
+
}
|
|
52
|
+
}
|
|
53
|
+
|
|
54
|
+
/**
|
|
55
|
+
* Raised when a tiered store's L2 fails and the failure is not suppressed
|
|
56
|
+
* (upstream `E_L2_CACHE_ERROR`, kept verbatim). `cause` is the L2's error.
|
|
57
|
+
*/
|
|
58
|
+
export class L2CacheError extends EchoError {
|
|
59
|
+
constructor(operation: string, cause: unknown) {
|
|
60
|
+
const reason = cause instanceof Error ? cause.message : String(cause);
|
|
61
|
+
super(
|
|
62
|
+
"E_L2_CACHE_ERROR",
|
|
63
|
+
`Echo: the L2 cache failed during ${operation}: ${reason}`,
|
|
64
|
+
{ cause },
|
|
65
|
+
);
|
|
66
|
+
}
|
|
67
|
+
}
|
|
68
|
+
|
|
5
69
|
/** Raised when a factory exceeds its configured `hardTimeout`. */
|
|
6
|
-
export class TimeoutError extends
|
|
70
|
+
export class TimeoutError extends EchoError {
|
|
7
71
|
constructor(key: string, timeoutMs: number) {
|
|
8
|
-
super(
|
|
9
|
-
|
|
72
|
+
super(
|
|
73
|
+
"E_FACTORY_HARD_TIMEOUT",
|
|
74
|
+
`Echo: factory for "${key}" timed out after ${timeoutMs}ms`,
|
|
75
|
+
);
|
|
10
76
|
}
|
|
11
77
|
}
|
|
12
78
|
|
|
@@ -14,7 +80,7 @@ export class TimeoutError extends Error {
|
|
|
14
80
|
* Wraps an error thrown by a `getOrSet` factory. Passed to `onFactoryError`
|
|
15
81
|
* so callers can observe both foreground and background factory failures.
|
|
16
82
|
*/
|
|
17
|
-
export class FactoryError extends
|
|
83
|
+
export class FactoryError extends EchoError {
|
|
18
84
|
/** The cache key the factory was computing. */
|
|
19
85
|
readonly key: string;
|
|
20
86
|
/** The original error thrown by the factory. */
|
|
@@ -24,10 +90,41 @@ export class FactoryError extends Error {
|
|
|
24
90
|
|
|
25
91
|
constructor(key: string, cause: unknown, isBackground: boolean) {
|
|
26
92
|
const reason = cause instanceof Error ? cause.message : String(cause);
|
|
27
|
-
super(`Echo: factory for "${key}" failed: ${reason}`);
|
|
28
|
-
this.name = "FactoryError";
|
|
93
|
+
super("E_FACTORY_ERROR", `Echo: factory for "${key}" failed: ${reason}`);
|
|
29
94
|
this.key = key;
|
|
30
95
|
this.cause = cause;
|
|
31
96
|
this.isBackground = isBackground;
|
|
32
97
|
}
|
|
33
98
|
}
|
|
99
|
+
|
|
100
|
+
/**
|
|
101
|
+
* Raised for a `null` or `undefined` value — upstream's `E_UNDEFINED_VALUE`.
|
|
102
|
+
* A `TypeError`, as this refusal always was. Echo refuses `null` as well: a
|
|
103
|
+
* null cache write is almost always a bug.
|
|
104
|
+
*/
|
|
105
|
+
export class UndefinedValueError extends TypeError {
|
|
106
|
+
readonly code = "E_UNDEFINED_VALUE";
|
|
107
|
+
|
|
108
|
+
constructor() {
|
|
109
|
+
super("Echo: caching null/undefined values is not supported");
|
|
110
|
+
this.name = "UndefinedValueError";
|
|
111
|
+
}
|
|
112
|
+
}
|
|
113
|
+
|
|
114
|
+
/** Raised for an argument a method cannot work with. A `TypeError`. */
|
|
115
|
+
export class InvalidArgumentError extends TypeError {
|
|
116
|
+
readonly code = "E_ECHO_INVALID_ARGUMENT";
|
|
117
|
+
|
|
118
|
+
constructor(message: string) {
|
|
119
|
+
super(message);
|
|
120
|
+
this.name = "InvalidArgumentError";
|
|
121
|
+
}
|
|
122
|
+
}
|
|
123
|
+
|
|
124
|
+
/** Upstream's `errors` map, by code. */
|
|
125
|
+
export const errors = {
|
|
126
|
+
E_FACTORY_ERROR: FactoryError,
|
|
127
|
+
E_FACTORY_HARD_TIMEOUT: TimeoutError,
|
|
128
|
+
E_UNDEFINED_VALUE: UndefinedValueError,
|
|
129
|
+
E_L2_CACHE_ERROR: L2CacheError,
|
|
130
|
+
};
|
package/src/index.ts
CHANGED
|
@@ -13,7 +13,10 @@ import "./augmentations.js";
|
|
|
13
13
|
|
|
14
14
|
export type { CacheConfig, CacheDriver } from "./CacheManager.js";
|
|
15
15
|
export { CacheManager } from "./CacheManager.js";
|
|
16
|
-
export {
|
|
16
|
+
export {
|
|
17
|
+
MemoryDriver,
|
|
18
|
+
type MemoryDriverOptions,
|
|
19
|
+
} from "./drivers/MemoryDriver.js";
|
|
17
20
|
export type { RedisClient } from "./drivers/RedisDriver.js";
|
|
18
21
|
export { RedisDriver } from "./drivers/RedisDriver.js";
|
|
19
22
|
export type {
|
|
@@ -21,13 +24,24 @@ export type {
|
|
|
21
24
|
CacheBus,
|
|
22
25
|
TieredDriverOptions,
|
|
23
26
|
} from "./drivers/TieredDriver.js";
|
|
24
|
-
export { TieredDriver } from "./drivers/TieredDriver.js";
|
|
27
|
+
export { isBusMessage, TieredDriver } from "./drivers/TieredDriver.js";
|
|
25
28
|
export type { Duration } from "./duration.js";
|
|
26
29
|
export { parseDuration, resolveTtlSeconds } from "./duration.js";
|
|
27
30
|
export type { EchoProviderConfig } from "./EchoProvider.js";
|
|
28
|
-
export {
|
|
31
|
+
export {
|
|
32
|
+
EchoError,
|
|
33
|
+
errors,
|
|
34
|
+
FactoryError,
|
|
35
|
+
InvalidArgumentError,
|
|
36
|
+
InvalidDurationError,
|
|
37
|
+
L2CacheError,
|
|
38
|
+
LockTimeoutError,
|
|
39
|
+
TimeoutError,
|
|
40
|
+
UndefinedValueError,
|
|
41
|
+
} from "./errors.js";
|
|
29
42
|
export {
|
|
30
43
|
CacheStoreManager,
|
|
44
|
+
type DriverContext,
|
|
31
45
|
type DriverFactory,
|
|
32
46
|
drivers,
|
|
33
47
|
type MultiStoreConfig,
|
package/src/quasar.ts
CHANGED
|
@@ -12,8 +12,16 @@
|
|
|
12
12
|
*/
|
|
13
13
|
|
|
14
14
|
import type { RedisClient } from "./drivers/RedisDriver.js";
|
|
15
|
-
import
|
|
16
|
-
|
|
15
|
+
import {
|
|
16
|
+
type BusMessage,
|
|
17
|
+
type CacheBus,
|
|
18
|
+
isBusMessage,
|
|
19
|
+
} from "./drivers/TieredDriver.js";
|
|
20
|
+
import { EchoError } from "./errors.js";
|
|
21
|
+
import {
|
|
22
|
+
hasCommands,
|
|
23
|
+
quasarConnection as loadQuasarConnection,
|
|
24
|
+
} from "./vendor/quasarConnection.js";
|
|
17
25
|
|
|
18
26
|
/**
|
|
19
27
|
* The commands this driver actually issues.
|
|
@@ -36,18 +44,40 @@ const REQUIRED = [
|
|
|
36
44
|
"ttl",
|
|
37
45
|
] as const;
|
|
38
46
|
|
|
47
|
+
/**
|
|
48
|
+
* The connection is handed over only once it carries every command above.
|
|
49
|
+
* `keys` and `exists` are declared but never called, so not required either;
|
|
50
|
+
* `scan` stays optional, but when there it has to be a function too.
|
|
51
|
+
*/
|
|
52
|
+
function isRedisClient(value: unknown): value is RedisClient {
|
|
53
|
+
return (
|
|
54
|
+
hasCommands(value, REQUIRED) &&
|
|
55
|
+
(!("scan" in value) ||
|
|
56
|
+
value.scan === undefined ||
|
|
57
|
+
typeof value.scan === "function")
|
|
58
|
+
);
|
|
59
|
+
}
|
|
60
|
+
|
|
39
61
|
/**
|
|
40
62
|
* A resolver for `drivers.redis({ connection })` — quasar is loaded on the
|
|
41
63
|
* first cache command, not at config time.
|
|
42
64
|
*/
|
|
43
65
|
export function quasarConnection(name?: string): () => Promise<RedisClient> {
|
|
44
66
|
return async () =>
|
|
45
|
-
loadQuasarConnection
|
|
67
|
+
loadQuasarConnection({
|
|
46
68
|
pkg: "echo",
|
|
47
69
|
name,
|
|
48
70
|
required: REQUIRED,
|
|
71
|
+
isConnection: isRedisClient,
|
|
49
72
|
what: "the cache store",
|
|
50
|
-
raise: (
|
|
73
|
+
raise: (reason, message, cause) =>
|
|
74
|
+
new EchoError(
|
|
75
|
+
reason === "quasar-missing"
|
|
76
|
+
? "E_ECHO_QUASAR_MISSING"
|
|
77
|
+
: "E_ECHO_INCOMPLETE_CONNECTION",
|
|
78
|
+
message,
|
|
79
|
+
{ cause },
|
|
80
|
+
),
|
|
51
81
|
});
|
|
52
82
|
}
|
|
53
83
|
|
|
@@ -114,7 +144,8 @@ async function loadQuasar(context: string): Promise<unknown> {
|
|
|
114
144
|
? loaded
|
|
115
145
|
: Reflect.get(Object(loaded), "default");
|
|
116
146
|
} catch (cause) {
|
|
117
|
-
throw new
|
|
147
|
+
throw new EchoError(
|
|
148
|
+
"E_ECHO_QUASAR_MISSING",
|
|
118
149
|
`Echo: ${context}, but @c9up/quasar is not installed.\n pnpm add @c9up/quasar`,
|
|
119
150
|
{ cause },
|
|
120
151
|
);
|
|
@@ -153,7 +184,8 @@ export function quasarBus(options?: {
|
|
|
153
184
|
? loaded.connection(options?.connection)
|
|
154
185
|
: loaded;
|
|
155
186
|
if (!isPubSubSource(source)) {
|
|
156
|
-
throw new
|
|
187
|
+
throw new EchoError(
|
|
188
|
+
"E_ECHO_INCOMPLETE_CONNECTION",
|
|
157
189
|
"Echo: the quasar connection does not expose publish()/subscribe()",
|
|
158
190
|
);
|
|
159
191
|
}
|
|
@@ -169,11 +201,15 @@ export function quasarBus(options?: {
|
|
|
169
201
|
},
|
|
170
202
|
async subscribe(handler: (message: BusMessage) => void): Promise<void> {
|
|
171
203
|
const wrapper = (raw: string): void => {
|
|
204
|
+
let frame: unknown;
|
|
172
205
|
try {
|
|
173
|
-
|
|
206
|
+
frame = JSON.parse(raw);
|
|
174
207
|
} catch {
|
|
175
|
-
|
|
208
|
+
// A malformed frame is not a reason to stop listening.
|
|
209
|
+
return;
|
|
176
210
|
}
|
|
211
|
+
// Anything on the channel reaches here, not only what echo sent.
|
|
212
|
+
if (isBusMessage(frame)) handler(frame);
|
|
177
213
|
};
|
|
178
214
|
// AWAITED, and a reported failure becomes a rejection.
|
|
179
215
|
//
|
package/src/services/main.ts
CHANGED
|
@@ -11,7 +11,8 @@
|
|
|
11
11
|
* const cached = await cache.get<User>('user:42')
|
|
12
12
|
*/
|
|
13
13
|
|
|
14
|
-
import
|
|
14
|
+
import { CacheManager } from "../CacheManager.js";
|
|
15
|
+
import { EchoError } from "../errors.js";
|
|
15
16
|
|
|
16
17
|
let instance: CacheManager | undefined;
|
|
17
18
|
|
|
@@ -33,7 +34,29 @@ export function clearCache(): void {
|
|
|
33
34
|
instance = undefined;
|
|
34
35
|
}
|
|
35
36
|
|
|
36
|
-
|
|
37
|
+
/**
|
|
38
|
+
* What the proxy stands on. Never reached: every read goes through the trap
|
|
39
|
+
* below, to the bound manager or to the not-booted error. A real instance
|
|
40
|
+
* rather than an asserted `{}`, so the proxy is a `CacheManager` by type.
|
|
41
|
+
*/
|
|
42
|
+
const unbooted = (): Promise<never> => Promise.reject(notBooted());
|
|
43
|
+
const placeholder = new CacheManager({
|
|
44
|
+
get: unbooted,
|
|
45
|
+
set: unbooted,
|
|
46
|
+
delete: unbooted,
|
|
47
|
+
flush: unbooted,
|
|
48
|
+
has: unbooted,
|
|
49
|
+
});
|
|
50
|
+
|
|
51
|
+
function notBooted(): EchoError {
|
|
52
|
+
return new EchoError(
|
|
53
|
+
"E_ECHO_NOT_BOOTED",
|
|
54
|
+
"[echo] CacheManager singleton accessed before EchoProvider.boot() ran " +
|
|
55
|
+
"or `setCache(myCache)` was called. Wire one of them first.",
|
|
56
|
+
);
|
|
57
|
+
}
|
|
58
|
+
|
|
59
|
+
const cache: CacheManager = new Proxy(placeholder, {
|
|
37
60
|
get(_target, prop) {
|
|
38
61
|
// A module loader inspects what it imports before anyone uses it: it reads
|
|
39
62
|
// `then` to decide whether the namespace is thenable, and various symbols
|
|
@@ -44,12 +67,7 @@ const cache: CacheManager = new Proxy({} as CacheManager, {
|
|
|
44
67
|
if (typeof prop === "symbol" || prop === "then") {
|
|
45
68
|
return undefined;
|
|
46
69
|
}
|
|
47
|
-
if (!instance)
|
|
48
|
-
throw new Error(
|
|
49
|
-
"[echo] CacheManager singleton accessed before EchoProvider.boot() ran " +
|
|
50
|
-
"or `setCache(myCache)` was called. Wire one of them first.",
|
|
51
|
-
);
|
|
52
|
-
}
|
|
70
|
+
if (!instance) throw notBooted();
|
|
53
71
|
const value = Reflect.get(instance, prop, instance);
|
|
54
72
|
return typeof value === "function" ? value.bind(instance) : value;
|
|
55
73
|
},
|
package/src/stubs.ts
ADDED
|
@@ -0,0 +1,16 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Where this package's stubs live.
|
|
3
|
+
*
|
|
4
|
+
* Its own module, as upstream keeps it: a stub root is a path a package
|
|
5
|
+
* publishes, and a caller importing it should not have to import the
|
|
6
|
+
* configure hook to get it.
|
|
7
|
+
*
|
|
8
|
+
* `import.meta.dirname` rather than a URL — upstream reads it straight off
|
|
9
|
+
* `import.meta`, and deriving it from `import.meta.url` breaks wherever that
|
|
10
|
+
* is not a `file://` URL, which is what a test runner serving modules over
|
|
11
|
+
* HTTP hands you.
|
|
12
|
+
*/
|
|
13
|
+
|
|
14
|
+
import { join } from "node:path";
|
|
15
|
+
|
|
16
|
+
export const stubsRoot = join(import.meta.dirname, "..", "stubs");
|