@c9up/echo 0.2.3 → 0.2.5
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/README.md +1 -1
- package/dist/CacheManager.d.ts +13 -2
- package/dist/CacheManager.d.ts.map +1 -1
- package/dist/CacheManager.js +309 -56
- 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 +38 -11
- package/dist/StoreManager.d.ts.map +1 -1
- package/dist/StoreManager.js +80 -22
- 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 +1 -0
- package/dist/configure.d.ts.map +1 -1
- package/dist/configure.js +3 -0
- 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 +37 -1
- package/dist/drivers/MemoryDriver.d.ts.map +1 -1
- package/dist/drivers/MemoryDriver.js +170 -72
- package/dist/drivers/MemoryDriver.js.map +1 -1
- package/dist/drivers/RedisDriver.d.ts +15 -8
- package/dist/drivers/RedisDriver.d.ts.map +1 -1
- package/dist/drivers/RedisDriver.js +198 -97
- 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 +106 -19
- 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/types.d.ts +44 -2
- package/dist/types.d.ts.map +1 -1
- package/dist/vendor/quasarConnection.d.ts +44 -3
- package/dist/vendor/quasarConnection.d.ts.map +1 -1
- package/dist/vendor/quasarConnection.js +64 -23
- package/dist/vendor/quasarConnection.js.map +1 -1
- package/package.json +5 -1
- package/src/CacheManager.ts +367 -69
- package/src/EchoProvider.ts +45 -4
- package/src/StoreManager.ts +131 -35
- package/src/bytes.ts +38 -0
- package/src/claim.ts +22 -0
- package/src/configure.ts +4 -0
- 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 +221 -69
- package/src/drivers/RedisDriver.ts +234 -104
- 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 +145 -30
- package/src/services/main.ts +26 -8
- package/src/types.ts +46 -7
- package/src/vendor/quasarConnection.ts +105 -22
package/dist/CacheManager.js
CHANGED
|
@@ -8,28 +8,62 @@
|
|
|
8
8
|
* ttlSeconds)`, `getOrSet(key, ttlSeconds, factory)`). The object form is the
|
|
9
9
|
* canonical one; the positional form is kept for back-compat.
|
|
10
10
|
*/
|
|
11
|
+
import { claimed, hasUnref } from "./claim.js";
|
|
11
12
|
import { parseDuration, resolveTtlSeconds } from "./duration.js";
|
|
12
|
-
import { FactoryError, TimeoutError } from "./errors.js";
|
|
13
|
+
import { EchoError, FactoryError, InvalidArgumentError, InvalidDurationError, LockTimeoutError, TimeoutError, UndefinedValueError, } from "./errors.js";
|
|
13
14
|
function isTaggableDriver(driver) {
|
|
14
15
|
const candidate = driver;
|
|
15
16
|
return (typeof candidate.setWithTags === "function" &&
|
|
16
17
|
(typeof candidate.deleteByTag === "function" ||
|
|
17
18
|
typeof candidate.flushTags === "function"));
|
|
18
19
|
}
|
|
19
|
-
|
|
20
|
+
function notTaggable() {
|
|
21
|
+
return new EchoError("E_ECHO_NOT_TAGGABLE", "Echo: the configured driver does not support tag-based invalidation");
|
|
22
|
+
}
|
|
23
|
+
/** The longest delay `setTimeout` honours; past it Node fires after 1 ms. */
|
|
24
|
+
const MAX_TIMER_MS = 2_147_483_647;
|
|
25
|
+
/**
|
|
26
|
+
* Resolve an optional timeout {@link Duration} to milliseconds; `undefined`
|
|
27
|
+
* when unset or `Infinity` (no timeout).
|
|
28
|
+
*
|
|
29
|
+
* Checked, because `setTimeout` reads NaN, Infinity and anything past
|
|
30
|
+
* 2^31-1 ms as 1 ms: "never time out" became "time out at once", and every
|
|
31
|
+
* getOrSet rejected. A longer one is clamped to the longest timer there is
|
|
32
|
+
* (24.8 days); NaN and negatives mean nothing and are refused.
|
|
33
|
+
*/
|
|
20
34
|
function resolveMs(duration) {
|
|
21
35
|
if (duration === undefined || duration === null)
|
|
22
36
|
return undefined;
|
|
23
37
|
const seconds = typeof duration === "number" ? duration : parseDuration(duration);
|
|
24
|
-
|
|
38
|
+
if (seconds === Number.POSITIVE_INFINITY)
|
|
39
|
+
return undefined;
|
|
40
|
+
if (Number.isNaN(seconds) || seconds < 0) {
|
|
41
|
+
throw new InvalidDurationError(`Echo: a timeout must be a non-negative duration, or null for none — got ${String(duration)}`);
|
|
42
|
+
}
|
|
43
|
+
return Math.min(seconds * 1000, MAX_TIMER_MS);
|
|
25
44
|
}
|
|
26
|
-
|
|
27
|
-
|
|
28
|
-
|
|
29
|
-
|
|
30
|
-
|
|
31
|
-
|
|
45
|
+
/**
|
|
46
|
+
* A resolved TTL as a write event reports it: `null` for an entry that never
|
|
47
|
+
* expires, which the driver level spells `0`, so a listener does not read
|
|
48
|
+
* "lives zero seconds".
|
|
49
|
+
*/
|
|
50
|
+
function reportedTtl(seconds) {
|
|
51
|
+
return seconds === 0 ? null : seconds;
|
|
32
52
|
}
|
|
53
|
+
/** The default `graceBackoff`, as upstream's: 10 seconds. */
|
|
54
|
+
const DEFAULT_GRACE_BACKOFF_SECONDS = 10;
|
|
55
|
+
/**
|
|
56
|
+
* Resolve `graceBackoff` to seconds: the default when unset, `0` (off) for
|
|
57
|
+
* `null` or `0`. A negative or NaN one means nothing and is refused.
|
|
58
|
+
*/
|
|
59
|
+
function resolveBackoffSeconds(duration) {
|
|
60
|
+
const seconds = resolveTtlSeconds(duration, DEFAULT_GRACE_BACKOFF_SECONDS);
|
|
61
|
+
if (seconds < 0) {
|
|
62
|
+
throw new InvalidDurationError(`Echo: graceBackoff must be a non-negative duration, or null for none — got ${String(duration)}`);
|
|
63
|
+
}
|
|
64
|
+
return seconds;
|
|
65
|
+
}
|
|
66
|
+
const TIMEOUT = Symbol("echo.timeout");
|
|
33
67
|
function withTimeout(promise, ms) {
|
|
34
68
|
return new Promise((resolve, reject) => {
|
|
35
69
|
const timer = setTimeout(() => resolve(TIMEOUT), ms);
|
|
@@ -52,6 +86,7 @@ export class CacheManager {
|
|
|
52
86
|
#prefix;
|
|
53
87
|
#defaultTtl;
|
|
54
88
|
#defaultGrace;
|
|
89
|
+
#defaultGraceBackoff;
|
|
55
90
|
#defaultTimeout;
|
|
56
91
|
#defaultHardTimeout;
|
|
57
92
|
#defaultLockTimeout;
|
|
@@ -67,6 +102,7 @@ export class CacheManager {
|
|
|
67
102
|
"cache:written": new Set(),
|
|
68
103
|
"cache:deleted": new Set(),
|
|
69
104
|
"cache:cleared": new Set(),
|
|
105
|
+
"cache:expire": new Set(),
|
|
70
106
|
};
|
|
71
107
|
#shared;
|
|
72
108
|
/**
|
|
@@ -87,6 +123,7 @@ export class CacheManager {
|
|
|
87
123
|
this.#prefix = config?.prefix ?? "";
|
|
88
124
|
this.#defaultTtl = resolveTtlSeconds(config?.ttl, 3600);
|
|
89
125
|
this.#defaultGrace = config?.grace;
|
|
126
|
+
this.#defaultGraceBackoff = config?.graceBackoff;
|
|
90
127
|
this.#defaultTimeout = config?.timeout;
|
|
91
128
|
this.#defaultHardTimeout = config?.hardTimeout;
|
|
92
129
|
this.#defaultLockTimeout = config?.lockTimeout;
|
|
@@ -94,9 +131,26 @@ export class CacheManager {
|
|
|
94
131
|
this.#emitter = config?.emitter;
|
|
95
132
|
this.#shared = shared ?? { inflight: new Map() };
|
|
96
133
|
}
|
|
134
|
+
/** The store's name, as events report it (upstream `cache.name`). */
|
|
135
|
+
get name() {
|
|
136
|
+
return this.#name;
|
|
137
|
+
}
|
|
97
138
|
#prefixKey(key) {
|
|
98
139
|
return this.#prefix ? `${this.#prefix}:${key}` : key;
|
|
99
140
|
}
|
|
141
|
+
/**
|
|
142
|
+
* Tags live inside the namespace, exactly as keys do. They reached the
|
|
143
|
+
* driver bare, into one store-wide index, so `tenantA.deleteByTag(['user:1'])`
|
|
144
|
+
* also dropped tenantB's entries tagged `user:1`. Upstream scopes them the
|
|
145
|
+
* same way: its tag invalidations are entries of the namespaced stack.
|
|
146
|
+
*/
|
|
147
|
+
#prefixTags(tags) {
|
|
148
|
+
return tags.map((tag) => this.#prefixKey(tag));
|
|
149
|
+
}
|
|
150
|
+
/** Milliseconds since `started`, to two decimals: an event's `duration`. */
|
|
151
|
+
#since(started) {
|
|
152
|
+
return Math.round((performance.now() - started) * 100) / 100;
|
|
153
|
+
}
|
|
100
154
|
#emit(event, payload) {
|
|
101
155
|
// Not just called: an Adonis emitter's `emit` is `async` and REJECTS when
|
|
102
156
|
// a listener throws and the application registered no error handler
|
|
@@ -177,7 +231,7 @@ export class CacheManager {
|
|
|
177
231
|
return this.#stores.use(name);
|
|
178
232
|
if (name === undefined)
|
|
179
233
|
return this;
|
|
180
|
-
throw new
|
|
234
|
+
throw new EchoError("E_ECHO_UNKNOWN_STORE", `Echo: cannot use the "${name}" store — this cache is configured with a single store. ` +
|
|
181
235
|
"Declare `{ default, stores }` in config/cache.ts to name several.");
|
|
182
236
|
}
|
|
183
237
|
/** @internal Called by `CacheStoreManager` on the store it builds. */
|
|
@@ -279,26 +333,44 @@ export class CacheManager {
|
|
|
279
333
|
if (value === null || value === undefined) {
|
|
280
334
|
// Named divergence (fail-loud): unlike bento (which no-ops), echo throws
|
|
281
335
|
// on caching null/undefined — a null cache write is almost always a bug.
|
|
282
|
-
throw new
|
|
336
|
+
throw new UndefinedValueError();
|
|
337
|
+
}
|
|
338
|
+
if (ttlSeconds < 0) {
|
|
339
|
+
// A TTL in the past: the value has already expired. Kept only as
|
|
340
|
+
// a stale copy for its grace window, otherwise dropped — and the
|
|
341
|
+
// key's previous value with it, which a skipped write would have
|
|
342
|
+
// left being served. Upstream deletes the same way when the TTL
|
|
343
|
+
// is not positive and grace is off.
|
|
344
|
+
if (graceSeconds > 0 && this.#driver.setEntry) {
|
|
345
|
+
await this.#driver.setEntry(prefixed, value, {
|
|
346
|
+
expiresAt: Date.now() - 1,
|
|
347
|
+
graceSeconds,
|
|
348
|
+
tags: this.#prefixTags(tags),
|
|
349
|
+
});
|
|
350
|
+
return;
|
|
351
|
+
}
|
|
352
|
+
await this.#driver.delete(prefixed);
|
|
353
|
+
return;
|
|
283
354
|
}
|
|
284
355
|
if (this.#driver.setEntry) {
|
|
285
356
|
await this.#driver.setEntry(prefixed, value, {
|
|
286
357
|
ttlSeconds,
|
|
287
358
|
graceSeconds,
|
|
288
|
-
tags,
|
|
359
|
+
tags: this.#prefixTags(tags),
|
|
289
360
|
});
|
|
290
361
|
return;
|
|
291
362
|
}
|
|
292
363
|
if (tags.length > 0) {
|
|
293
364
|
if (!isTaggableDriver(this.#driver)) {
|
|
294
|
-
throw
|
|
365
|
+
throw notTaggable();
|
|
295
366
|
}
|
|
296
|
-
await this.#driver.setWithTags(prefixed, value, tags, ttlSeconds);
|
|
367
|
+
await this.#driver.setWithTags(prefixed, value, this.#prefixTags(tags), ttlSeconds);
|
|
297
368
|
return;
|
|
298
369
|
}
|
|
299
370
|
await this.#driver.set(prefixed, value, ttlSeconds);
|
|
300
371
|
}
|
|
301
372
|
async get(keyOrOptions) {
|
|
373
|
+
const started = performance.now();
|
|
302
374
|
await this.#whenConnected();
|
|
303
375
|
const key = typeof keyOrOptions === "string" ? keyOrOptions : keyOrOptions.key;
|
|
304
376
|
const graceSeconds = typeof keyOrOptions === "string"
|
|
@@ -312,6 +384,7 @@ export class CacheManager {
|
|
|
312
384
|
value: entry.value,
|
|
313
385
|
store: this.#name,
|
|
314
386
|
graced: false,
|
|
387
|
+
duration: this.#since(started),
|
|
315
388
|
});
|
|
316
389
|
return entry.value;
|
|
317
390
|
}
|
|
@@ -321,10 +394,15 @@ export class CacheManager {
|
|
|
321
394
|
value: entry.value,
|
|
322
395
|
store: this.#name,
|
|
323
396
|
graced: true,
|
|
397
|
+
duration: this.#since(started),
|
|
324
398
|
});
|
|
325
399
|
return entry.value;
|
|
326
400
|
}
|
|
327
|
-
this.#emit("cache:miss", {
|
|
401
|
+
this.#emit("cache:miss", {
|
|
402
|
+
key,
|
|
403
|
+
store: this.#name,
|
|
404
|
+
duration: this.#since(started),
|
|
405
|
+
});
|
|
328
406
|
if (defaultValue !== undefined) {
|
|
329
407
|
return defaultValue instanceof Function ? defaultValue() : defaultValue;
|
|
330
408
|
}
|
|
@@ -336,6 +414,7 @@ export class CacheManager {
|
|
|
336
414
|
return undefined;
|
|
337
415
|
}
|
|
338
416
|
async set(keyOrOptions, value, ttlSeconds) {
|
|
417
|
+
const started = performance.now();
|
|
339
418
|
await this.#whenConnected();
|
|
340
419
|
let key;
|
|
341
420
|
let val;
|
|
@@ -345,7 +424,7 @@ export class CacheManager {
|
|
|
345
424
|
if (typeof keyOrOptions === "string") {
|
|
346
425
|
key = keyOrOptions;
|
|
347
426
|
val = value;
|
|
348
|
-
ttl = ttlSeconds
|
|
427
|
+
ttl = resolveTtlSeconds(ttlSeconds, this.#defaultTtl);
|
|
349
428
|
graceSeconds = 0;
|
|
350
429
|
tags = [];
|
|
351
430
|
}
|
|
@@ -357,17 +436,28 @@ export class CacheManager {
|
|
|
357
436
|
tags = keyOrOptions.tags ?? [];
|
|
358
437
|
}
|
|
359
438
|
await this.#writeValue(this.#prefixKey(key), val, ttl, graceSeconds, tags);
|
|
360
|
-
this.#emit("cache:written", {
|
|
439
|
+
this.#emit("cache:written", {
|
|
440
|
+
key,
|
|
441
|
+
value: val,
|
|
442
|
+
store: this.#name,
|
|
443
|
+
ttl: reportedTtl(ttl),
|
|
444
|
+
duration: this.#since(started),
|
|
445
|
+
});
|
|
361
446
|
}
|
|
362
447
|
/** Set a value that never expires (bento `setForever`). */
|
|
363
448
|
setForever(options) {
|
|
364
449
|
return this.set({ ...options, ttl: null });
|
|
365
450
|
}
|
|
366
451
|
async delete(keyOrOptions) {
|
|
452
|
+
const started = performance.now();
|
|
367
453
|
await this.#whenConnected();
|
|
368
454
|
const key = typeof keyOrOptions === "string" ? keyOrOptions : keyOrOptions.key;
|
|
369
455
|
const deleted = await this.#driver.delete(this.#prefixKey(key));
|
|
370
|
-
this.#emit("cache:deleted", {
|
|
456
|
+
this.#emit("cache:deleted", {
|
|
457
|
+
key,
|
|
458
|
+
store: this.#name,
|
|
459
|
+
duration: this.#since(started),
|
|
460
|
+
});
|
|
371
461
|
return deleted;
|
|
372
462
|
}
|
|
373
463
|
/** Delete multiple keys (bento `deleteMany`). */
|
|
@@ -378,8 +468,13 @@ export class CacheManager {
|
|
|
378
468
|
: keysOrOptions.keys;
|
|
379
469
|
let all = true;
|
|
380
470
|
for (const key of keys) {
|
|
471
|
+
const started = performance.now();
|
|
381
472
|
const ok = await this.#driver.delete(this.#prefixKey(key));
|
|
382
|
-
this.#emit("cache:deleted", {
|
|
473
|
+
this.#emit("cache:deleted", {
|
|
474
|
+
key,
|
|
475
|
+
store: this.#name,
|
|
476
|
+
duration: this.#since(started),
|
|
477
|
+
});
|
|
383
478
|
if (!ok)
|
|
384
479
|
all = false;
|
|
385
480
|
}
|
|
@@ -395,7 +490,10 @@ export class CacheManager {
|
|
|
395
490
|
const key = typeof keyOrOptions === "string" ? keyOrOptions : keyOrOptions.key;
|
|
396
491
|
return !(await this.has(key));
|
|
397
492
|
}
|
|
398
|
-
/**
|
|
493
|
+
/**
|
|
494
|
+
* Read a key and delete it in one step (bento `pull`). Resolves to
|
|
495
|
+
* `undefined` on a miss, as `get` does, and deletes nothing then.
|
|
496
|
+
*/
|
|
399
497
|
async pull(key) {
|
|
400
498
|
await this.#whenConnected();
|
|
401
499
|
const value = await this.get(key);
|
|
@@ -408,6 +506,7 @@ export class CacheManager {
|
|
|
408
506
|
* window (bento `expire`). Without grace this is equivalent to a delete.
|
|
409
507
|
*/
|
|
410
508
|
async expire(keyOrOptions) {
|
|
509
|
+
const started = performance.now();
|
|
411
510
|
await this.#whenConnected();
|
|
412
511
|
const key = typeof keyOrOptions === "string" ? keyOrOptions : keyOrOptions.key;
|
|
413
512
|
const prefixed = this.#prefixKey(key);
|
|
@@ -415,18 +514,34 @@ export class CacheManager {
|
|
|
415
514
|
const entry = await this.#readEntry(prefixed);
|
|
416
515
|
if (entry === null)
|
|
417
516
|
return false;
|
|
517
|
+
let expired;
|
|
418
518
|
if (graceSeconds > 0 && this.#driver.setEntry) {
|
|
419
519
|
// Mark the entry stale RIGHT NOW (logical expiry one ms in the past) while
|
|
420
520
|
// keeping it physically for the grace window. A positive `ttlSeconds`
|
|
421
521
|
// would leave a brief fresh window during which the value is still served
|
|
422
522
|
// and the factory never runs.
|
|
523
|
+
//
|
|
524
|
+
// With its tags, as the driver read them (already scoped to this
|
|
525
|
+
// namespace): rewritten without them, the stale copy was served for
|
|
526
|
+
// the whole grace window while deleteByTag no longer reached it.
|
|
423
527
|
await this.#driver.setEntry(prefixed, entry.value, {
|
|
424
528
|
expiresAt: Date.now() - 1,
|
|
425
529
|
graceSeconds,
|
|
530
|
+
tags: entry.tags ?? [],
|
|
531
|
+
});
|
|
532
|
+
expired = true;
|
|
533
|
+
}
|
|
534
|
+
else {
|
|
535
|
+
expired = await this.#driver.delete(prefixed);
|
|
536
|
+
}
|
|
537
|
+
if (expired) {
|
|
538
|
+
this.#emit("cache:expire", {
|
|
539
|
+
key,
|
|
540
|
+
store: this.#name,
|
|
541
|
+
duration: this.#since(started),
|
|
426
542
|
});
|
|
427
|
-
return true;
|
|
428
543
|
}
|
|
429
|
-
return
|
|
544
|
+
return expired;
|
|
430
545
|
}
|
|
431
546
|
/**
|
|
432
547
|
* Clear this cache — the whole store, or only this namespace's subtree.
|
|
@@ -437,18 +552,30 @@ export class CacheManager {
|
|
|
437
552
|
* handing the driver the prefix.
|
|
438
553
|
*/
|
|
439
554
|
async clear() {
|
|
555
|
+
const started = performance.now();
|
|
440
556
|
await this.#whenConnected();
|
|
441
557
|
// The separator is part of it: `tenant-a` must not take `tenant-abc`
|
|
442
558
|
// with it, and every key under this view is written `<prefix>:<key>`.
|
|
443
559
|
await this.#driver.flush(this.#prefix ? `${this.#prefix}:` : undefined);
|
|
444
|
-
this.#emit("cache:cleared", {
|
|
560
|
+
this.#emit("cache:cleared", {
|
|
561
|
+
store: this.#name,
|
|
562
|
+
duration: this.#since(started),
|
|
563
|
+
});
|
|
445
564
|
}
|
|
446
565
|
// ---- tags ------------------------------------------------------------
|
|
447
566
|
/** Set a value with tags for grouped invalidation (bento parity). */
|
|
448
567
|
async setWithTags(key, value, tags, ttlSeconds) {
|
|
568
|
+
const started = performance.now();
|
|
449
569
|
await this.#whenConnected();
|
|
450
|
-
|
|
451
|
-
this.#
|
|
570
|
+
const ttl = resolveTtlSeconds(ttlSeconds, this.#defaultTtl);
|
|
571
|
+
await this.#writeValue(this.#prefixKey(key), value, ttl, 0, tags);
|
|
572
|
+
this.#emit("cache:written", {
|
|
573
|
+
key,
|
|
574
|
+
value,
|
|
575
|
+
store: this.#name,
|
|
576
|
+
ttl: reportedTtl(ttl),
|
|
577
|
+
duration: this.#since(started),
|
|
578
|
+
});
|
|
452
579
|
}
|
|
453
580
|
async deleteByTag(tagsOrOptions) {
|
|
454
581
|
await this.#whenConnected();
|
|
@@ -456,12 +583,13 @@ export class CacheManager {
|
|
|
456
583
|
? tagsOrOptions
|
|
457
584
|
: tagsOrOptions.tags;
|
|
458
585
|
if (!isTaggableDriver(this.#driver)) {
|
|
459
|
-
throw
|
|
586
|
+
throw notTaggable();
|
|
460
587
|
}
|
|
588
|
+
const scoped = this.#prefixTags(tags);
|
|
461
589
|
if (typeof this.#driver.deleteByTag === "function") {
|
|
462
|
-
return this.#driver.deleteByTag(
|
|
590
|
+
return this.#driver.deleteByTag(scoped);
|
|
463
591
|
}
|
|
464
|
-
return this.#driver.flushTags(
|
|
592
|
+
return this.#driver.flushTags(scoped);
|
|
465
593
|
}
|
|
466
594
|
/** @deprecated alias of {@link deleteByTag}. */
|
|
467
595
|
async flushTags(tags) {
|
|
@@ -478,6 +606,7 @@ export class CacheManager {
|
|
|
478
606
|
prefix: this.#prefix ? `${this.#prefix}:${ns}` : ns,
|
|
479
607
|
ttl: this.#defaultTtl,
|
|
480
608
|
grace: this.#defaultGrace,
|
|
609
|
+
graceBackoff: this.#defaultGraceBackoff,
|
|
481
610
|
timeout: this.#defaultTimeout,
|
|
482
611
|
hardTimeout: this.#defaultHardTimeout,
|
|
483
612
|
lockTimeout: this.#defaultLockTimeout,
|
|
@@ -486,66 +615,169 @@ export class CacheManager {
|
|
|
486
615
|
}, this.#shared);
|
|
487
616
|
}
|
|
488
617
|
// ---- getOrSet --------------------------------------------------------
|
|
489
|
-
#normalizeGetOrSet(a, b, c) {
|
|
618
|
+
#normalizeGetOrSet(a, b, c, started) {
|
|
490
619
|
if (typeof a === "string") {
|
|
491
620
|
if (typeof c !== "function") {
|
|
492
|
-
throw new
|
|
621
|
+
throw new InvalidArgumentError("Echo: getOrSet(key, ttl, factory) requires a factory function");
|
|
493
622
|
}
|
|
494
623
|
return {
|
|
495
624
|
key: a,
|
|
496
625
|
factory: c,
|
|
497
626
|
ttlSeconds: resolveTtlSeconds(b, this.#defaultTtl),
|
|
498
627
|
graceSeconds: resolveTtlSeconds(this.#defaultGrace, 0),
|
|
628
|
+
graceBackoffSeconds: resolveBackoffSeconds(this.#defaultGraceBackoff),
|
|
499
629
|
timeoutMs: resolveMs(this.#defaultTimeout),
|
|
500
630
|
hardTimeoutMs: resolveMs(this.#defaultHardTimeout),
|
|
501
631
|
lockTimeoutMs: resolveMs(this.#defaultLockTimeout),
|
|
502
632
|
tags: [],
|
|
633
|
+
started,
|
|
503
634
|
};
|
|
504
635
|
}
|
|
636
|
+
// Checked in this form too: a config value or a JSON body reaching here
|
|
637
|
+
// untyped made the call fail with a bare TypeError from deep inside the
|
|
638
|
+
// single-flight bookkeeping, instead of a refusal naming the argument.
|
|
639
|
+
if (typeof a.factory !== "function") {
|
|
640
|
+
throw new InvalidArgumentError("Echo: getOrSet({ key, factory }) requires a factory function");
|
|
641
|
+
}
|
|
505
642
|
return {
|
|
506
643
|
key: a.key,
|
|
507
644
|
factory: a.factory,
|
|
508
645
|
ttlSeconds: resolveTtlSeconds(a.ttl, this.#defaultTtl),
|
|
509
646
|
graceSeconds: resolveTtlSeconds(a.grace ?? this.#defaultGrace, 0),
|
|
647
|
+
graceBackoffSeconds: resolveBackoffSeconds(a.graceBackoff === undefined
|
|
648
|
+
? this.#defaultGraceBackoff
|
|
649
|
+
: a.graceBackoff),
|
|
510
650
|
timeoutMs: resolveMs(a.timeout ?? this.#defaultTimeout),
|
|
511
651
|
hardTimeoutMs: resolveMs(a.hardTimeout ?? this.#defaultHardTimeout),
|
|
512
652
|
lockTimeoutMs: resolveMs(a.lockTimeout ?? this.#defaultLockTimeout),
|
|
513
653
|
tags: a.tags ?? [],
|
|
514
654
|
onFactoryError: a.onFactoryError,
|
|
655
|
+
started,
|
|
515
656
|
};
|
|
516
657
|
}
|
|
517
658
|
/**
|
|
518
|
-
* Run
|
|
519
|
-
* fresh value on success; on
|
|
520
|
-
*
|
|
659
|
+
* Run the single-flight factory for `prefixed` and register it as the
|
|
660
|
+
* key's in-flight record. Resolves to the fresh value on success; on
|
|
661
|
+
* failure it calls `onFactoryError` and either resolves to `staleValue`
|
|
662
|
+
* (when a stale fallback exists) or rejects. The record is removed once it
|
|
663
|
+
* settles, whichever way.
|
|
521
664
|
*/
|
|
522
|
-
#invokeFactory(prefixed, o, hasStale, staleValue) {
|
|
665
|
+
#invokeFactory(prefixed, o, hasStale, staleValue, staleTags) {
|
|
523
666
|
const run = async () => {
|
|
524
667
|
try {
|
|
525
|
-
|
|
668
|
+
// Called a microtask later, never inline. A factory that throws
|
|
669
|
+
// before returning a promise ran this `finally` synchronously,
|
|
670
|
+
// BEFORE the record below was stored: the rejected promise then
|
|
671
|
+
// stayed in the map for good, and every later call for the key
|
|
672
|
+
// joined it instead of running the factory again.
|
|
673
|
+
const value = await Promise.resolve().then(() => o.factory());
|
|
674
|
+
// The write is timed on its own: the factory's time is the
|
|
675
|
+
// miss's, reported once the call is served. Timed from the call,
|
|
676
|
+
// the two overlapped and a profiler summing them counted the
|
|
677
|
+
// factory twice.
|
|
678
|
+
const writing = performance.now();
|
|
526
679
|
await this.#writeValue(prefixed, value, o.ttlSeconds, o.graceSeconds, o.tags);
|
|
527
680
|
this.#emit("cache:written", {
|
|
528
681
|
key: o.key,
|
|
529
682
|
value,
|
|
530
683
|
store: this.#name,
|
|
684
|
+
ttl: reportedTtl(o.ttlSeconds),
|
|
685
|
+
duration: this.#since(writing),
|
|
531
686
|
});
|
|
532
|
-
return value;
|
|
687
|
+
return { value, fresh: true };
|
|
533
688
|
}
|
|
534
689
|
catch (error) {
|
|
535
690
|
o.onFactoryError?.(new FactoryError(o.key, error, hasStale));
|
|
536
|
-
if (hasStale && staleValue !== undefined)
|
|
537
|
-
|
|
691
|
+
if (hasStale && staleValue !== undefined) {
|
|
692
|
+
await this.#applyGraceBackoff(prefixed, staleValue, staleTags, o);
|
|
693
|
+
return { value: staleValue, fresh: false };
|
|
694
|
+
}
|
|
538
695
|
throw error;
|
|
539
696
|
}
|
|
540
697
|
finally {
|
|
541
|
-
this
|
|
698
|
+
// Only this run's own record: a later leader's must survive it.
|
|
699
|
+
if (this.#shared.inflight.get(prefixed) === record) {
|
|
700
|
+
this.#shared.inflight.delete(prefixed);
|
|
701
|
+
}
|
|
542
702
|
}
|
|
543
703
|
};
|
|
544
|
-
|
|
704
|
+
const outcome = run();
|
|
705
|
+
// What a joiner reads: the value alone. Marked handled here, since
|
|
706
|
+
// nobody may ever join; each joiner still sees a rejection on its own
|
|
707
|
+
// chain, and the leader on `outcome`.
|
|
708
|
+
const shared = outcome.then((settled) => settled.value);
|
|
709
|
+
shared.catch(() => { });
|
|
710
|
+
const record = { promise: shared };
|
|
711
|
+
this.#shared.inflight.set(prefixed, record);
|
|
712
|
+
return outcome;
|
|
713
|
+
}
|
|
714
|
+
/**
|
|
715
|
+
* Serve the stale value as fresh for `graceBackoff` after its factory
|
|
716
|
+
* failed (upstream `graceBackoff`, default 10 s).
|
|
717
|
+
*
|
|
718
|
+
* Without it the entry stayed stale, and every request for the grace
|
|
719
|
+
* window ran the factory again: a backend that was down got hit once per
|
|
720
|
+
* request, since single-flight only collapses callers that overlap.
|
|
721
|
+
*
|
|
722
|
+
* NAMED DEVIATION: the backoff runs from NOW. Upstream adds it to the
|
|
723
|
+
* entry's old logical expiry, which leaves an entry that went stale more
|
|
724
|
+
* than `graceBackoff` ago still stale, so the factory is retried at once.
|
|
725
|
+
*
|
|
726
|
+
* Written only over the stale copy it read: an entry rewritten or deleted
|
|
727
|
+
* while the factory ran (a `set`, a `deleteByTag`) is not overwritten, nor
|
|
728
|
+
* an invalidated one brought back.
|
|
729
|
+
*/
|
|
730
|
+
async #applyGraceBackoff(prefixed, value, tags, o) {
|
|
731
|
+
if (o.graceBackoffSeconds <= 0 || !this.#driver.setEntry)
|
|
732
|
+
return;
|
|
733
|
+
try {
|
|
734
|
+
const current = await this.#readEntry(prefixed);
|
|
735
|
+
if (current === null || !current.stale)
|
|
736
|
+
return;
|
|
737
|
+
await this.#driver.setEntry(prefixed, value, {
|
|
738
|
+
expiresAt: Date.now() + o.graceBackoffSeconds * 1000,
|
|
739
|
+
graceSeconds: o.graceSeconds,
|
|
740
|
+
// Already scoped to the namespace: they are what the driver read.
|
|
741
|
+
tags,
|
|
742
|
+
});
|
|
743
|
+
}
|
|
744
|
+
catch {
|
|
745
|
+
// The stale value is still served. The factory's own failure is
|
|
746
|
+
// what `onFactoryError` reports; a store too unwell to take the
|
|
747
|
+
// backoff only means the factory is tried again sooner.
|
|
748
|
+
}
|
|
749
|
+
}
|
|
750
|
+
/**
|
|
751
|
+
* Report how the LEADER's call was served, once its factory settled: a
|
|
752
|
+
* miss when the factory produced the value, as upstream reports it after
|
|
753
|
+
* the factory has run; a graced hit when the factory failed and the stale
|
|
754
|
+
* value stood in for it. A joiner ran no factory and reports neither.
|
|
755
|
+
*/
|
|
756
|
+
#settled(o, outcome, leader) {
|
|
757
|
+
if (!leader)
|
|
758
|
+
return outcome.value;
|
|
759
|
+
if (outcome.fresh) {
|
|
760
|
+
this.#emit("cache:miss", {
|
|
761
|
+
key: o.key,
|
|
762
|
+
store: this.#name,
|
|
763
|
+
duration: this.#since(o.started),
|
|
764
|
+
});
|
|
765
|
+
}
|
|
766
|
+
else {
|
|
767
|
+
this.#emit("cache:hit", {
|
|
768
|
+
key: o.key,
|
|
769
|
+
value: outcome.value,
|
|
770
|
+
store: this.#name,
|
|
771
|
+
graced: true,
|
|
772
|
+
duration: this.#since(o.started),
|
|
773
|
+
});
|
|
774
|
+
}
|
|
775
|
+
return outcome.value;
|
|
545
776
|
}
|
|
546
777
|
async getOrSet(a, b, c) {
|
|
778
|
+
const started = performance.now();
|
|
547
779
|
await this.#whenConnected();
|
|
548
|
-
const o = this.#normalizeGetOrSet(a, b, c);
|
|
780
|
+
const o = this.#normalizeGetOrSet(a, b, c, started);
|
|
549
781
|
const prefixed = this.#prefixKey(o.key);
|
|
550
782
|
const entry = await this.#readEntry(prefixed);
|
|
551
783
|
if (entry && !entry.stale) {
|
|
@@ -554,21 +786,28 @@ export class CacheManager {
|
|
|
554
786
|
value: entry.value,
|
|
555
787
|
store: this.#name,
|
|
556
788
|
graced: false,
|
|
789
|
+
duration: this.#since(started),
|
|
557
790
|
});
|
|
558
791
|
return entry.value;
|
|
559
792
|
}
|
|
560
793
|
const hasStale = entry?.stale === true && o.graceSeconds > 0;
|
|
561
794
|
const staleValue = hasStale ? entry.value : undefined;
|
|
562
|
-
|
|
563
|
-
|
|
564
|
-
|
|
565
|
-
|
|
566
|
-
|
|
567
|
-
|
|
795
|
+
const staleTags = hasStale ? (entry.tags ?? []) : [];
|
|
796
|
+
const record = this.#shared.inflight.get(prefixed);
|
|
797
|
+
// Joining another caller's factory, rather than running our own.
|
|
798
|
+
const joined = record !== undefined;
|
|
799
|
+
let factoryPromise;
|
|
800
|
+
if (record === undefined) {
|
|
801
|
+
factoryPromise = this.#invokeFactory(prefixed, o, hasStale, staleValue, staleTags);
|
|
802
|
+
}
|
|
803
|
+
else {
|
|
804
|
+
// The map holds every key's factory, whatever its type; what the
|
|
805
|
+
// leader computes for this key is what this caller reads.
|
|
806
|
+
factoryPromise = record.promise.then((value) => ({
|
|
807
|
+
value: claimed(value),
|
|
808
|
+
fresh: false,
|
|
809
|
+
}));
|
|
568
810
|
}
|
|
569
|
-
// Single-flight join point: the shared map is heterogeneous (many T), so
|
|
570
|
-
// this generic re-assertion is unavoidable (mirrors echo <=0.1.5).
|
|
571
|
-
const factoryPromise = record.promise;
|
|
572
811
|
if (hasStale && staleValue !== undefined) {
|
|
573
812
|
// Stale-while-revalidate: serve stale up to the soft timeout (default 0
|
|
574
813
|
// = serve immediately), let the factory refresh in the background.
|
|
@@ -583,19 +822,33 @@ export class CacheManager {
|
|
|
583
822
|
value: staleValue,
|
|
584
823
|
store: this.#name,
|
|
585
824
|
graced: true,
|
|
825
|
+
duration: this.#since(started),
|
|
586
826
|
});
|
|
587
827
|
return staleValue;
|
|
588
828
|
}
|
|
589
|
-
return result;
|
|
829
|
+
return this.#settled(o, result, !joined);
|
|
830
|
+
}
|
|
831
|
+
// A joiner waits at most `lockTimeout` for the leader, stale value or
|
|
832
|
+
// not, as upstream bounds its lock acquisition either way. It was read
|
|
833
|
+
// on the stale path only, so behind a factory that hung every caller
|
|
834
|
+
// for the key waited forever. The leader is not bound by it: it holds
|
|
835
|
+
// the lock, and `hardTimeout` is what bounds its factory.
|
|
836
|
+
const lockMs = joined ? o.lockTimeoutMs : undefined;
|
|
837
|
+
const hardMs = o.hardTimeoutMs;
|
|
838
|
+
if (lockMs !== undefined && (hardMs === undefined || lockMs < hardMs)) {
|
|
839
|
+
const result = await withTimeout(factoryPromise, lockMs);
|
|
840
|
+
if (result === TIMEOUT)
|
|
841
|
+
throw new LockTimeoutError(o.key, lockMs);
|
|
842
|
+
return this.#settled(o, result, !joined);
|
|
590
843
|
}
|
|
591
|
-
if (
|
|
592
|
-
const result = await withTimeout(factoryPromise,
|
|
844
|
+
if (hardMs !== undefined) {
|
|
845
|
+
const result = await withTimeout(factoryPromise, hardMs);
|
|
593
846
|
if (result === TIMEOUT) {
|
|
594
|
-
throw new TimeoutError(o.key,
|
|
847
|
+
throw new TimeoutError(o.key, hardMs);
|
|
595
848
|
}
|
|
596
|
-
return result;
|
|
849
|
+
return this.#settled(o, result, !joined);
|
|
597
850
|
}
|
|
598
|
-
return factoryPromise;
|
|
851
|
+
return this.#settled(o, await factoryPromise, !joined);
|
|
599
852
|
}
|
|
600
853
|
/** Like {@link getOrSet} but the stored value never expires (bento `getOrSetForever`). */
|
|
601
854
|
getOrSetForever(options) {
|