@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/src/CacheManager.ts
CHANGED
|
@@ -9,8 +9,17 @@
|
|
|
9
9
|
* canonical one; the positional form is kept for back-compat.
|
|
10
10
|
*/
|
|
11
11
|
|
|
12
|
+
import { claimed, hasUnref } from "./claim.js";
|
|
12
13
|
import { type Duration, parseDuration, resolveTtlSeconds } from "./duration.js";
|
|
13
|
-
import {
|
|
14
|
+
import {
|
|
15
|
+
EchoError,
|
|
16
|
+
FactoryError,
|
|
17
|
+
InvalidArgumentError,
|
|
18
|
+
InvalidDurationError,
|
|
19
|
+
LockTimeoutError,
|
|
20
|
+
TimeoutError,
|
|
21
|
+
UndefinedValueError,
|
|
22
|
+
} from "./errors.js";
|
|
14
23
|
import type {
|
|
15
24
|
CacheEmitter,
|
|
16
25
|
CacheEntry,
|
|
@@ -42,25 +51,66 @@ function isTaggableDriver(driver: CacheDriver): driver is TaggableDriver {
|
|
|
42
51
|
);
|
|
43
52
|
}
|
|
44
53
|
|
|
45
|
-
|
|
54
|
+
function notTaggable(): EchoError {
|
|
55
|
+
return new EchoError(
|
|
56
|
+
"E_ECHO_NOT_TAGGABLE",
|
|
57
|
+
"Echo: the configured driver does not support tag-based invalidation",
|
|
58
|
+
);
|
|
59
|
+
}
|
|
60
|
+
|
|
61
|
+
/** The longest delay `setTimeout` honours; past it Node fires after 1 ms. */
|
|
62
|
+
const MAX_TIMER_MS = 2_147_483_647;
|
|
63
|
+
|
|
64
|
+
/**
|
|
65
|
+
* Resolve an optional timeout {@link Duration} to milliseconds; `undefined`
|
|
66
|
+
* when unset or `Infinity` (no timeout).
|
|
67
|
+
*
|
|
68
|
+
* Checked, because `setTimeout` reads NaN, Infinity and anything past
|
|
69
|
+
* 2^31-1 ms as 1 ms: "never time out" became "time out at once", and every
|
|
70
|
+
* getOrSet rejected. A longer one is clamped to the longest timer there is
|
|
71
|
+
* (24.8 days); NaN and negatives mean nothing and are refused.
|
|
72
|
+
*/
|
|
46
73
|
function resolveMs(duration: Duration | undefined): number | undefined {
|
|
47
74
|
if (duration === undefined || duration === null) return undefined;
|
|
48
75
|
const seconds =
|
|
49
76
|
typeof duration === "number" ? duration : parseDuration(duration);
|
|
50
|
-
|
|
77
|
+
if (seconds === Number.POSITIVE_INFINITY) return undefined;
|
|
78
|
+
if (Number.isNaN(seconds) || seconds < 0) {
|
|
79
|
+
throw new InvalidDurationError(
|
|
80
|
+
`Echo: a timeout must be a non-negative duration, or null for none — got ${String(duration)}`,
|
|
81
|
+
);
|
|
82
|
+
}
|
|
83
|
+
return Math.min(seconds * 1000, MAX_TIMER_MS);
|
|
51
84
|
}
|
|
52
85
|
|
|
53
|
-
|
|
86
|
+
/**
|
|
87
|
+
* A resolved TTL as a write event reports it: `null` for an entry that never
|
|
88
|
+
* expires, which the driver level spells `0`, so a listener does not read
|
|
89
|
+
* "lives zero seconds".
|
|
90
|
+
*/
|
|
91
|
+
function reportedTtl(seconds: number): number | null {
|
|
92
|
+
return seconds === 0 ? null : seconds;
|
|
93
|
+
}
|
|
54
94
|
|
|
55
|
-
/**
|
|
56
|
-
|
|
57
|
-
|
|
58
|
-
|
|
59
|
-
|
|
60
|
-
|
|
61
|
-
|
|
95
|
+
/** The default `graceBackoff`, as upstream's: 10 seconds. */
|
|
96
|
+
const DEFAULT_GRACE_BACKOFF_SECONDS = 10;
|
|
97
|
+
|
|
98
|
+
/**
|
|
99
|
+
* Resolve `graceBackoff` to seconds: the default when unset, `0` (off) for
|
|
100
|
+
* `null` or `0`. A negative or NaN one means nothing and is refused.
|
|
101
|
+
*/
|
|
102
|
+
function resolveBackoffSeconds(duration: Duration | undefined): number {
|
|
103
|
+
const seconds = resolveTtlSeconds(duration, DEFAULT_GRACE_BACKOFF_SECONDS);
|
|
104
|
+
if (seconds < 0) {
|
|
105
|
+
throw new InvalidDurationError(
|
|
106
|
+
`Echo: graceBackoff must be a non-negative duration, or null for none — got ${String(duration)}`,
|
|
107
|
+
);
|
|
108
|
+
}
|
|
109
|
+
return seconds;
|
|
62
110
|
}
|
|
63
111
|
|
|
112
|
+
const TIMEOUT: unique symbol = Symbol("echo.timeout");
|
|
113
|
+
|
|
64
114
|
function withTimeout<T>(
|
|
65
115
|
promise: Promise<T>,
|
|
66
116
|
ms: number,
|
|
@@ -96,6 +146,12 @@ export interface CacheConfig {
|
|
|
96
146
|
ttl?: Duration;
|
|
97
147
|
/** Default grace period (stale-while-revalidate) as a {@link Duration}. */
|
|
98
148
|
grace?: Duration;
|
|
149
|
+
/**
|
|
150
|
+
* How long a stale value is served as fresh after its factory failed,
|
|
151
|
+
* before the factory is tried again. Default `'10s'`; `0` or `null` retries
|
|
152
|
+
* on the next call.
|
|
153
|
+
*/
|
|
154
|
+
graceBackoff?: Duration;
|
|
99
155
|
/** Default soft timeout for `getOrSet` (return stale if the factory is slower). */
|
|
100
156
|
timeout?: Duration;
|
|
101
157
|
/** Default hard timeout for `getOrSet`. */
|
|
@@ -104,10 +160,17 @@ export interface CacheConfig {
|
|
|
104
160
|
lockTimeout?: Duration;
|
|
105
161
|
/** Store name reported in events (default `"default"`). */
|
|
106
162
|
name?: string;
|
|
107
|
-
/** Optional event emitter (`cache:hit` / `miss` / `written` / `deleted` / `cleared`). */
|
|
163
|
+
/** Optional event emitter (`cache:hit` / `miss` / `written` / `deleted` / `cleared` / `expire`). */
|
|
108
164
|
emitter?: CacheEmitter;
|
|
109
165
|
}
|
|
110
166
|
|
|
167
|
+
/** What a factory run settled to: its own value, or the stale one standing in. */
|
|
168
|
+
interface FactoryOutcome<T> {
|
|
169
|
+
value: T;
|
|
170
|
+
/** `true` when the factory produced `value`; `false` for the stale fallback. */
|
|
171
|
+
fresh: boolean;
|
|
172
|
+
}
|
|
173
|
+
|
|
111
174
|
/** Shared single-flight state — one map per store, threaded through namespaces. */
|
|
112
175
|
interface SharedState {
|
|
113
176
|
inflight: Map<string, { promise: Promise<unknown> }>;
|
|
@@ -118,11 +181,14 @@ interface NormalizedGetOrSet<T> {
|
|
|
118
181
|
factory: Factory<T>;
|
|
119
182
|
ttlSeconds: number;
|
|
120
183
|
graceSeconds: number;
|
|
184
|
+
graceBackoffSeconds: number;
|
|
121
185
|
timeoutMs: number | undefined;
|
|
122
186
|
hardTimeoutMs: number | undefined;
|
|
123
187
|
lockTimeoutMs: number | undefined;
|
|
124
188
|
tags: string[];
|
|
125
189
|
onFactoryError?: (error: FactoryError) => void;
|
|
190
|
+
/** `performance.now()` when the call came in: what its events time from. */
|
|
191
|
+
started: number;
|
|
126
192
|
}
|
|
127
193
|
|
|
128
194
|
/** The slice of `CacheStoreManager` a store it built needs to reach back into. */
|
|
@@ -137,6 +203,7 @@ export class CacheManager {
|
|
|
137
203
|
#prefix: string;
|
|
138
204
|
#defaultTtl: number;
|
|
139
205
|
#defaultGrace: Duration | undefined;
|
|
206
|
+
#defaultGraceBackoff: Duration | undefined;
|
|
140
207
|
#defaultTimeout: Duration | undefined;
|
|
141
208
|
#defaultHardTimeout: Duration | undefined;
|
|
142
209
|
#defaultLockTimeout: Duration | undefined;
|
|
@@ -154,6 +221,7 @@ export class CacheManager {
|
|
|
154
221
|
"cache:written": new Set(),
|
|
155
222
|
"cache:deleted": new Set(),
|
|
156
223
|
"cache:cleared": new Set(),
|
|
224
|
+
"cache:expire": new Set(),
|
|
157
225
|
};
|
|
158
226
|
#shared: SharedState;
|
|
159
227
|
/**
|
|
@@ -175,6 +243,7 @@ export class CacheManager {
|
|
|
175
243
|
this.#prefix = config?.prefix ?? "";
|
|
176
244
|
this.#defaultTtl = resolveTtlSeconds(config?.ttl, 3600);
|
|
177
245
|
this.#defaultGrace = config?.grace;
|
|
246
|
+
this.#defaultGraceBackoff = config?.graceBackoff;
|
|
178
247
|
this.#defaultTimeout = config?.timeout;
|
|
179
248
|
this.#defaultHardTimeout = config?.hardTimeout;
|
|
180
249
|
this.#defaultLockTimeout = config?.lockTimeout;
|
|
@@ -183,10 +252,30 @@ export class CacheManager {
|
|
|
183
252
|
this.#shared = shared ?? { inflight: new Map() };
|
|
184
253
|
}
|
|
185
254
|
|
|
255
|
+
/** The store's name, as events report it (upstream `cache.name`). */
|
|
256
|
+
get name(): string {
|
|
257
|
+
return this.#name;
|
|
258
|
+
}
|
|
259
|
+
|
|
186
260
|
#prefixKey(key: string): string {
|
|
187
261
|
return this.#prefix ? `${this.#prefix}:${key}` : key;
|
|
188
262
|
}
|
|
189
263
|
|
|
264
|
+
/**
|
|
265
|
+
* Tags live inside the namespace, exactly as keys do. They reached the
|
|
266
|
+
* driver bare, into one store-wide index, so `tenantA.deleteByTag(['user:1'])`
|
|
267
|
+
* also dropped tenantB's entries tagged `user:1`. Upstream scopes them the
|
|
268
|
+
* same way: its tag invalidations are entries of the namespaced stack.
|
|
269
|
+
*/
|
|
270
|
+
#prefixTags(tags: string[]): string[] {
|
|
271
|
+
return tags.map((tag) => this.#prefixKey(tag));
|
|
272
|
+
}
|
|
273
|
+
|
|
274
|
+
/** Milliseconds since `started`, to two decimals: an event's `duration`. */
|
|
275
|
+
#since(started: number): number {
|
|
276
|
+
return Math.round((performance.now() - started) * 100) / 100;
|
|
277
|
+
}
|
|
278
|
+
|
|
190
279
|
#emit<E extends keyof CacheEventMap>(
|
|
191
280
|
event: E,
|
|
192
281
|
payload: CacheEventMap[E],
|
|
@@ -287,7 +376,8 @@ export class CacheManager {
|
|
|
287
376
|
use(name?: string): CacheManager {
|
|
288
377
|
if (this.#stores) return this.#stores.use(name);
|
|
289
378
|
if (name === undefined) return this;
|
|
290
|
-
throw new
|
|
379
|
+
throw new EchoError(
|
|
380
|
+
"E_ECHO_UNKNOWN_STORE",
|
|
291
381
|
`Echo: cannot use the "${name}" store — this cache is configured with a single store. ` +
|
|
292
382
|
"Declare `{ default, stores }` in config/cache.ts to name several.",
|
|
293
383
|
);
|
|
@@ -397,25 +487,43 @@ export class CacheManager {
|
|
|
397
487
|
if (value === null || value === undefined) {
|
|
398
488
|
// Named divergence (fail-loud): unlike bento (which no-ops), echo throws
|
|
399
489
|
// on caching null/undefined — a null cache write is almost always a bug.
|
|
400
|
-
throw new
|
|
401
|
-
|
|
402
|
-
|
|
490
|
+
throw new UndefinedValueError();
|
|
491
|
+
}
|
|
492
|
+
if (ttlSeconds < 0) {
|
|
493
|
+
// A TTL in the past: the value has already expired. Kept only as
|
|
494
|
+
// a stale copy for its grace window, otherwise dropped — and the
|
|
495
|
+
// key's previous value with it, which a skipped write would have
|
|
496
|
+
// left being served. Upstream deletes the same way when the TTL
|
|
497
|
+
// is not positive and grace is off.
|
|
498
|
+
if (graceSeconds > 0 && this.#driver.setEntry) {
|
|
499
|
+
await this.#driver.setEntry(prefixed, value, {
|
|
500
|
+
expiresAt: Date.now() - 1,
|
|
501
|
+
graceSeconds,
|
|
502
|
+
tags: this.#prefixTags(tags),
|
|
503
|
+
});
|
|
504
|
+
return;
|
|
505
|
+
}
|
|
506
|
+
await this.#driver.delete(prefixed);
|
|
507
|
+
return;
|
|
403
508
|
}
|
|
404
509
|
if (this.#driver.setEntry) {
|
|
405
510
|
await this.#driver.setEntry(prefixed, value, {
|
|
406
511
|
ttlSeconds,
|
|
407
512
|
graceSeconds,
|
|
408
|
-
tags,
|
|
513
|
+
tags: this.#prefixTags(tags),
|
|
409
514
|
});
|
|
410
515
|
return;
|
|
411
516
|
}
|
|
412
517
|
if (tags.length > 0) {
|
|
413
518
|
if (!isTaggableDriver(this.#driver)) {
|
|
414
|
-
throw
|
|
415
|
-
"Echo: the configured driver does not support tag-based invalidation",
|
|
416
|
-
);
|
|
519
|
+
throw notTaggable();
|
|
417
520
|
}
|
|
418
|
-
await this.#driver.setWithTags(
|
|
521
|
+
await this.#driver.setWithTags(
|
|
522
|
+
prefixed,
|
|
523
|
+
value,
|
|
524
|
+
this.#prefixTags(tags),
|
|
525
|
+
ttlSeconds,
|
|
526
|
+
);
|
|
419
527
|
return;
|
|
420
528
|
}
|
|
421
529
|
await this.#driver.set(prefixed, value, ttlSeconds);
|
|
@@ -428,6 +536,7 @@ export class CacheManager {
|
|
|
428
536
|
async get<T = unknown>(
|
|
429
537
|
keyOrOptions: string | GetOptions<T>,
|
|
430
538
|
): Promise<T | undefined> {
|
|
539
|
+
const started = performance.now();
|
|
431
540
|
await this.#whenConnected();
|
|
432
541
|
const key =
|
|
433
542
|
typeof keyOrOptions === "string" ? keyOrOptions : keyOrOptions.key;
|
|
@@ -445,6 +554,7 @@ export class CacheManager {
|
|
|
445
554
|
value: entry.value,
|
|
446
555
|
store: this.#name,
|
|
447
556
|
graced: false,
|
|
557
|
+
duration: this.#since(started),
|
|
448
558
|
});
|
|
449
559
|
return entry.value;
|
|
450
560
|
}
|
|
@@ -454,11 +564,16 @@ export class CacheManager {
|
|
|
454
564
|
value: entry.value,
|
|
455
565
|
store: this.#name,
|
|
456
566
|
graced: true,
|
|
567
|
+
duration: this.#since(started),
|
|
457
568
|
});
|
|
458
569
|
return entry.value;
|
|
459
570
|
}
|
|
460
571
|
|
|
461
|
-
this.#emit("cache:miss", {
|
|
572
|
+
this.#emit("cache:miss", {
|
|
573
|
+
key,
|
|
574
|
+
store: this.#name,
|
|
575
|
+
duration: this.#since(started),
|
|
576
|
+
});
|
|
462
577
|
if (defaultValue !== undefined) {
|
|
463
578
|
return defaultValue instanceof Function ? defaultValue() : defaultValue;
|
|
464
579
|
}
|
|
@@ -479,6 +594,7 @@ export class CacheManager {
|
|
|
479
594
|
value?: unknown,
|
|
480
595
|
ttlSeconds?: number,
|
|
481
596
|
): Promise<void> {
|
|
597
|
+
const started = performance.now();
|
|
482
598
|
await this.#whenConnected();
|
|
483
599
|
let key: string;
|
|
484
600
|
let val: unknown;
|
|
@@ -488,7 +604,7 @@ export class CacheManager {
|
|
|
488
604
|
if (typeof keyOrOptions === "string") {
|
|
489
605
|
key = keyOrOptions;
|
|
490
606
|
val = value;
|
|
491
|
-
ttl = ttlSeconds
|
|
607
|
+
ttl = resolveTtlSeconds(ttlSeconds, this.#defaultTtl);
|
|
492
608
|
graceSeconds = 0;
|
|
493
609
|
tags = [];
|
|
494
610
|
} else {
|
|
@@ -502,7 +618,13 @@ export class CacheManager {
|
|
|
502
618
|
tags = keyOrOptions.tags ?? [];
|
|
503
619
|
}
|
|
504
620
|
await this.#writeValue(this.#prefixKey(key), val, ttl, graceSeconds, tags);
|
|
505
|
-
this.#emit("cache:written", {
|
|
621
|
+
this.#emit("cache:written", {
|
|
622
|
+
key,
|
|
623
|
+
value: val,
|
|
624
|
+
store: this.#name,
|
|
625
|
+
ttl: reportedTtl(ttl),
|
|
626
|
+
duration: this.#since(started),
|
|
627
|
+
});
|
|
506
628
|
}
|
|
507
629
|
|
|
508
630
|
/** Set a value that never expires (bento `setForever`). */
|
|
@@ -515,11 +637,16 @@ export class CacheManager {
|
|
|
515
637
|
delete(key: string): Promise<boolean>;
|
|
516
638
|
delete(options: DeleteOptions): Promise<boolean>;
|
|
517
639
|
async delete(keyOrOptions: string | DeleteOptions): Promise<boolean> {
|
|
640
|
+
const started = performance.now();
|
|
518
641
|
await this.#whenConnected();
|
|
519
642
|
const key =
|
|
520
643
|
typeof keyOrOptions === "string" ? keyOrOptions : keyOrOptions.key;
|
|
521
644
|
const deleted = await this.#driver.delete(this.#prefixKey(key));
|
|
522
|
-
this.#emit("cache:deleted", {
|
|
645
|
+
this.#emit("cache:deleted", {
|
|
646
|
+
key,
|
|
647
|
+
store: this.#name,
|
|
648
|
+
duration: this.#since(started),
|
|
649
|
+
});
|
|
523
650
|
return deleted;
|
|
524
651
|
}
|
|
525
652
|
|
|
@@ -533,8 +660,13 @@ export class CacheManager {
|
|
|
533
660
|
: keysOrOptions.keys;
|
|
534
661
|
let all = true;
|
|
535
662
|
for (const key of keys) {
|
|
663
|
+
const started = performance.now();
|
|
536
664
|
const ok = await this.#driver.delete(this.#prefixKey(key));
|
|
537
|
-
this.#emit("cache:deleted", {
|
|
665
|
+
this.#emit("cache:deleted", {
|
|
666
|
+
key,
|
|
667
|
+
store: this.#name,
|
|
668
|
+
duration: this.#since(started),
|
|
669
|
+
});
|
|
538
670
|
if (!ok) all = false;
|
|
539
671
|
}
|
|
540
672
|
return all;
|
|
@@ -556,7 +688,10 @@ export class CacheManager {
|
|
|
556
688
|
return !(await this.has(key));
|
|
557
689
|
}
|
|
558
690
|
|
|
559
|
-
/**
|
|
691
|
+
/**
|
|
692
|
+
* Read a key and delete it in one step (bento `pull`). Resolves to
|
|
693
|
+
* `undefined` on a miss, as `get` does, and deletes nothing then.
|
|
694
|
+
*/
|
|
560
695
|
async pull<T = unknown>(key: string): Promise<T | undefined> {
|
|
561
696
|
await this.#whenConnected();
|
|
562
697
|
const value = await this.get<T>(key);
|
|
@@ -569,6 +704,7 @@ export class CacheManager {
|
|
|
569
704
|
* window (bento `expire`). Without grace this is equivalent to a delete.
|
|
570
705
|
*/
|
|
571
706
|
async expire(keyOrOptions: string | ExpireOptions): Promise<boolean> {
|
|
707
|
+
const started = performance.now();
|
|
572
708
|
await this.#whenConnected();
|
|
573
709
|
const key =
|
|
574
710
|
typeof keyOrOptions === "string" ? keyOrOptions : keyOrOptions.key;
|
|
@@ -576,18 +712,33 @@ export class CacheManager {
|
|
|
576
712
|
const graceSeconds = resolveTtlSeconds(this.#defaultGrace, 0);
|
|
577
713
|
const entry = await this.#readEntry<unknown>(prefixed);
|
|
578
714
|
if (entry === null) return false;
|
|
715
|
+
let expired: boolean;
|
|
579
716
|
if (graceSeconds > 0 && this.#driver.setEntry) {
|
|
580
717
|
// Mark the entry stale RIGHT NOW (logical expiry one ms in the past) while
|
|
581
718
|
// keeping it physically for the grace window. A positive `ttlSeconds`
|
|
582
719
|
// would leave a brief fresh window during which the value is still served
|
|
583
720
|
// and the factory never runs.
|
|
721
|
+
//
|
|
722
|
+
// With its tags, as the driver read them (already scoped to this
|
|
723
|
+
// namespace): rewritten without them, the stale copy was served for
|
|
724
|
+
// the whole grace window while deleteByTag no longer reached it.
|
|
584
725
|
await this.#driver.setEntry(prefixed, entry.value, {
|
|
585
726
|
expiresAt: Date.now() - 1,
|
|
586
727
|
graceSeconds,
|
|
728
|
+
tags: entry.tags ?? [],
|
|
729
|
+
});
|
|
730
|
+
expired = true;
|
|
731
|
+
} else {
|
|
732
|
+
expired = await this.#driver.delete(prefixed);
|
|
733
|
+
}
|
|
734
|
+
if (expired) {
|
|
735
|
+
this.#emit("cache:expire", {
|
|
736
|
+
key,
|
|
737
|
+
store: this.#name,
|
|
738
|
+
duration: this.#since(started),
|
|
587
739
|
});
|
|
588
|
-
return true;
|
|
589
740
|
}
|
|
590
|
-
return
|
|
741
|
+
return expired;
|
|
591
742
|
}
|
|
592
743
|
|
|
593
744
|
/**
|
|
@@ -599,11 +750,15 @@ export class CacheManager {
|
|
|
599
750
|
* handing the driver the prefix.
|
|
600
751
|
*/
|
|
601
752
|
async clear(): Promise<void> {
|
|
753
|
+
const started = performance.now();
|
|
602
754
|
await this.#whenConnected();
|
|
603
755
|
// The separator is part of it: `tenant-a` must not take `tenant-abc`
|
|
604
756
|
// with it, and every key under this view is written `<prefix>:<key>`.
|
|
605
757
|
await this.#driver.flush(this.#prefix ? `${this.#prefix}:` : undefined);
|
|
606
|
-
this.#emit("cache:cleared", {
|
|
758
|
+
this.#emit("cache:cleared", {
|
|
759
|
+
store: this.#name,
|
|
760
|
+
duration: this.#since(started),
|
|
761
|
+
});
|
|
607
762
|
}
|
|
608
763
|
|
|
609
764
|
// ---- tags ------------------------------------------------------------
|
|
@@ -615,15 +770,17 @@ export class CacheManager {
|
|
|
615
770
|
tags: string[],
|
|
616
771
|
ttlSeconds?: number,
|
|
617
772
|
): Promise<void> {
|
|
773
|
+
const started = performance.now();
|
|
618
774
|
await this.#whenConnected();
|
|
619
|
-
|
|
620
|
-
|
|
775
|
+
const ttl = resolveTtlSeconds(ttlSeconds, this.#defaultTtl);
|
|
776
|
+
await this.#writeValue(this.#prefixKey(key), value, ttl, 0, tags);
|
|
777
|
+
this.#emit("cache:written", {
|
|
778
|
+
key,
|
|
621
779
|
value,
|
|
622
|
-
|
|
623
|
-
|
|
624
|
-
|
|
625
|
-
);
|
|
626
|
-
this.#emit("cache:written", { key, value, store: this.#name });
|
|
780
|
+
store: this.#name,
|
|
781
|
+
ttl: reportedTtl(ttl),
|
|
782
|
+
duration: this.#since(started),
|
|
783
|
+
});
|
|
627
784
|
}
|
|
628
785
|
|
|
629
786
|
/** Invalidate all entries carrying any of the given tags (bento `deleteByTag`). */
|
|
@@ -637,14 +794,13 @@ export class CacheManager {
|
|
|
637
794
|
? tagsOrOptions
|
|
638
795
|
: tagsOrOptions.tags;
|
|
639
796
|
if (!isTaggableDriver(this.#driver)) {
|
|
640
|
-
throw
|
|
641
|
-
"Echo: the configured driver does not support tag-based invalidation",
|
|
642
|
-
);
|
|
797
|
+
throw notTaggable();
|
|
643
798
|
}
|
|
799
|
+
const scoped = this.#prefixTags(tags);
|
|
644
800
|
if (typeof this.#driver.deleteByTag === "function") {
|
|
645
|
-
return this.#driver.deleteByTag(
|
|
801
|
+
return this.#driver.deleteByTag(scoped);
|
|
646
802
|
}
|
|
647
|
-
return this.#driver.flushTags(
|
|
803
|
+
return this.#driver.flushTags(scoped);
|
|
648
804
|
}
|
|
649
805
|
|
|
650
806
|
/** @deprecated alias of {@link deleteByTag}. */
|
|
@@ -666,6 +822,7 @@ export class CacheManager {
|
|
|
666
822
|
prefix: this.#prefix ? `${this.#prefix}:${ns}` : ns,
|
|
667
823
|
ttl: this.#defaultTtl,
|
|
668
824
|
grace: this.#defaultGrace,
|
|
825
|
+
graceBackoff: this.#defaultGraceBackoff,
|
|
669
826
|
timeout: this.#defaultTimeout,
|
|
670
827
|
hardTimeout: this.#defaultHardTimeout,
|
|
671
828
|
lockTimeout: this.#defaultLockTimeout,
|
|
@@ -682,10 +839,11 @@ export class CacheManager {
|
|
|
682
839
|
a: string | GetOrSetOptions<T>,
|
|
683
840
|
b: number | undefined,
|
|
684
841
|
c: Factory<T> | undefined,
|
|
842
|
+
started: number,
|
|
685
843
|
): NormalizedGetOrSet<T> {
|
|
686
844
|
if (typeof a === "string") {
|
|
687
845
|
if (typeof c !== "function") {
|
|
688
|
-
throw new
|
|
846
|
+
throw new InvalidArgumentError(
|
|
689
847
|
"Echo: getOrSet(key, ttl, factory) requires a factory function",
|
|
690
848
|
);
|
|
691
849
|
}
|
|
@@ -694,39 +852,68 @@ export class CacheManager {
|
|
|
694
852
|
factory: c,
|
|
695
853
|
ttlSeconds: resolveTtlSeconds(b, this.#defaultTtl),
|
|
696
854
|
graceSeconds: resolveTtlSeconds(this.#defaultGrace, 0),
|
|
855
|
+
graceBackoffSeconds: resolveBackoffSeconds(this.#defaultGraceBackoff),
|
|
697
856
|
timeoutMs: resolveMs(this.#defaultTimeout),
|
|
698
857
|
hardTimeoutMs: resolveMs(this.#defaultHardTimeout),
|
|
699
858
|
lockTimeoutMs: resolveMs(this.#defaultLockTimeout),
|
|
700
859
|
tags: [],
|
|
860
|
+
started,
|
|
701
861
|
};
|
|
702
862
|
}
|
|
863
|
+
// Checked in this form too: a config value or a JSON body reaching here
|
|
864
|
+
// untyped made the call fail with a bare TypeError from deep inside the
|
|
865
|
+
// single-flight bookkeeping, instead of a refusal naming the argument.
|
|
866
|
+
if (typeof a.factory !== "function") {
|
|
867
|
+
throw new InvalidArgumentError(
|
|
868
|
+
"Echo: getOrSet({ key, factory }) requires a factory function",
|
|
869
|
+
);
|
|
870
|
+
}
|
|
703
871
|
return {
|
|
704
872
|
key: a.key,
|
|
705
873
|
factory: a.factory,
|
|
706
874
|
ttlSeconds: resolveTtlSeconds(a.ttl, this.#defaultTtl),
|
|
707
875
|
graceSeconds: resolveTtlSeconds(a.grace ?? this.#defaultGrace, 0),
|
|
876
|
+
graceBackoffSeconds: resolveBackoffSeconds(
|
|
877
|
+
a.graceBackoff === undefined
|
|
878
|
+
? this.#defaultGraceBackoff
|
|
879
|
+
: a.graceBackoff,
|
|
880
|
+
),
|
|
708
881
|
timeoutMs: resolveMs(a.timeout ?? this.#defaultTimeout),
|
|
709
882
|
hardTimeoutMs: resolveMs(a.hardTimeout ?? this.#defaultHardTimeout),
|
|
710
883
|
lockTimeoutMs: resolveMs(a.lockTimeout ?? this.#defaultLockTimeout),
|
|
711
884
|
tags: a.tags ?? [],
|
|
712
885
|
onFactoryError: a.onFactoryError,
|
|
886
|
+
started,
|
|
713
887
|
};
|
|
714
888
|
}
|
|
715
889
|
|
|
716
890
|
/**
|
|
717
|
-
* Run
|
|
718
|
-
* fresh value on success; on
|
|
719
|
-
*
|
|
891
|
+
* Run the single-flight factory for `prefixed` and register it as the
|
|
892
|
+
* key's in-flight record. Resolves to the fresh value on success; on
|
|
893
|
+
* failure it calls `onFactoryError` and either resolves to `staleValue`
|
|
894
|
+
* (when a stale fallback exists) or rejects. The record is removed once it
|
|
895
|
+
* settles, whichever way.
|
|
720
896
|
*/
|
|
721
897
|
#invokeFactory<T>(
|
|
722
898
|
prefixed: string,
|
|
723
899
|
o: NormalizedGetOrSet<T>,
|
|
724
900
|
hasStale: boolean,
|
|
725
901
|
staleValue: T | undefined,
|
|
726
|
-
|
|
727
|
-
|
|
902
|
+
staleTags: string[],
|
|
903
|
+
): Promise<FactoryOutcome<T>> {
|
|
904
|
+
const run = async (): Promise<FactoryOutcome<T>> => {
|
|
728
905
|
try {
|
|
729
|
-
|
|
906
|
+
// Called a microtask later, never inline. A factory that throws
|
|
907
|
+
// before returning a promise ran this `finally` synchronously,
|
|
908
|
+
// BEFORE the record below was stored: the rejected promise then
|
|
909
|
+
// stayed in the map for good, and every later call for the key
|
|
910
|
+
// joined it instead of running the factory again.
|
|
911
|
+
const value = await Promise.resolve().then(() => o.factory());
|
|
912
|
+
// The write is timed on its own: the factory's time is the
|
|
913
|
+
// miss's, reported once the call is served. Timed from the call,
|
|
914
|
+
// the two overlapped and a profiler summing them counted the
|
|
915
|
+
// factory twice.
|
|
916
|
+
const writing = performance.now();
|
|
730
917
|
await this.#writeValue(
|
|
731
918
|
prefixed,
|
|
732
919
|
value,
|
|
@@ -738,17 +925,102 @@ export class CacheManager {
|
|
|
738
925
|
key: o.key,
|
|
739
926
|
value,
|
|
740
927
|
store: this.#name,
|
|
928
|
+
ttl: reportedTtl(o.ttlSeconds),
|
|
929
|
+
duration: this.#since(writing),
|
|
741
930
|
});
|
|
742
|
-
return value;
|
|
931
|
+
return { value, fresh: true };
|
|
743
932
|
} catch (error) {
|
|
744
933
|
o.onFactoryError?.(new FactoryError(o.key, error, hasStale));
|
|
745
|
-
if (hasStale && staleValue !== undefined)
|
|
934
|
+
if (hasStale && staleValue !== undefined) {
|
|
935
|
+
await this.#applyGraceBackoff(prefixed, staleValue, staleTags, o);
|
|
936
|
+
return { value: staleValue, fresh: false };
|
|
937
|
+
}
|
|
746
938
|
throw error;
|
|
747
939
|
} finally {
|
|
748
|
-
this
|
|
940
|
+
// Only this run's own record: a later leader's must survive it.
|
|
941
|
+
if (this.#shared.inflight.get(prefixed) === record) {
|
|
942
|
+
this.#shared.inflight.delete(prefixed);
|
|
943
|
+
}
|
|
749
944
|
}
|
|
750
945
|
};
|
|
751
|
-
|
|
946
|
+
const outcome = run();
|
|
947
|
+
// What a joiner reads: the value alone. Marked handled here, since
|
|
948
|
+
// nobody may ever join; each joiner still sees a rejection on its own
|
|
949
|
+
// chain, and the leader on `outcome`.
|
|
950
|
+
const shared = outcome.then((settled) => settled.value);
|
|
951
|
+
shared.catch(() => {});
|
|
952
|
+
const record = { promise: shared };
|
|
953
|
+
this.#shared.inflight.set(prefixed, record);
|
|
954
|
+
return outcome;
|
|
955
|
+
}
|
|
956
|
+
|
|
957
|
+
/**
|
|
958
|
+
* Serve the stale value as fresh for `graceBackoff` after its factory
|
|
959
|
+
* failed (upstream `graceBackoff`, default 10 s).
|
|
960
|
+
*
|
|
961
|
+
* Without it the entry stayed stale, and every request for the grace
|
|
962
|
+
* window ran the factory again: a backend that was down got hit once per
|
|
963
|
+
* request, since single-flight only collapses callers that overlap.
|
|
964
|
+
*
|
|
965
|
+
* NAMED DEVIATION: the backoff runs from NOW. Upstream adds it to the
|
|
966
|
+
* entry's old logical expiry, which leaves an entry that went stale more
|
|
967
|
+
* than `graceBackoff` ago still stale, so the factory is retried at once.
|
|
968
|
+
*
|
|
969
|
+
* Written only over the stale copy it read: an entry rewritten or deleted
|
|
970
|
+
* while the factory ran (a `set`, a `deleteByTag`) is not overwritten, nor
|
|
971
|
+
* an invalidated one brought back.
|
|
972
|
+
*/
|
|
973
|
+
async #applyGraceBackoff<T>(
|
|
974
|
+
prefixed: string,
|
|
975
|
+
value: T,
|
|
976
|
+
tags: string[],
|
|
977
|
+
o: NormalizedGetOrSet<T>,
|
|
978
|
+
): Promise<void> {
|
|
979
|
+
if (o.graceBackoffSeconds <= 0 || !this.#driver.setEntry) return;
|
|
980
|
+
try {
|
|
981
|
+
const current = await this.#readEntry<T>(prefixed);
|
|
982
|
+
if (current === null || !current.stale) return;
|
|
983
|
+
await this.#driver.setEntry(prefixed, value, {
|
|
984
|
+
expiresAt: Date.now() + o.graceBackoffSeconds * 1000,
|
|
985
|
+
graceSeconds: o.graceSeconds,
|
|
986
|
+
// Already scoped to the namespace: they are what the driver read.
|
|
987
|
+
tags,
|
|
988
|
+
});
|
|
989
|
+
} catch {
|
|
990
|
+
// The stale value is still served. The factory's own failure is
|
|
991
|
+
// what `onFactoryError` reports; a store too unwell to take the
|
|
992
|
+
// backoff only means the factory is tried again sooner.
|
|
993
|
+
}
|
|
994
|
+
}
|
|
995
|
+
|
|
996
|
+
/**
|
|
997
|
+
* Report how the LEADER's call was served, once its factory settled: a
|
|
998
|
+
* miss when the factory produced the value, as upstream reports it after
|
|
999
|
+
* the factory has run; a graced hit when the factory failed and the stale
|
|
1000
|
+
* value stood in for it. A joiner ran no factory and reports neither.
|
|
1001
|
+
*/
|
|
1002
|
+
#settled<T>(
|
|
1003
|
+
o: NormalizedGetOrSet<T>,
|
|
1004
|
+
outcome: FactoryOutcome<T>,
|
|
1005
|
+
leader: boolean,
|
|
1006
|
+
): T {
|
|
1007
|
+
if (!leader) return outcome.value;
|
|
1008
|
+
if (outcome.fresh) {
|
|
1009
|
+
this.#emit("cache:miss", {
|
|
1010
|
+
key: o.key,
|
|
1011
|
+
store: this.#name,
|
|
1012
|
+
duration: this.#since(o.started),
|
|
1013
|
+
});
|
|
1014
|
+
} else {
|
|
1015
|
+
this.#emit("cache:hit", {
|
|
1016
|
+
key: o.key,
|
|
1017
|
+
value: outcome.value,
|
|
1018
|
+
store: this.#name,
|
|
1019
|
+
graced: true,
|
|
1020
|
+
duration: this.#since(o.started),
|
|
1021
|
+
});
|
|
1022
|
+
}
|
|
1023
|
+
return outcome.value;
|
|
752
1024
|
}
|
|
753
1025
|
|
|
754
1026
|
getOrSet<T>(key: string, ttlSeconds: number, factory: Factory<T>): Promise<T>;
|
|
@@ -758,8 +1030,9 @@ export class CacheManager {
|
|
|
758
1030
|
b?: number,
|
|
759
1031
|
c?: Factory<T>,
|
|
760
1032
|
): Promise<T> {
|
|
1033
|
+
const started = performance.now();
|
|
761
1034
|
await this.#whenConnected();
|
|
762
|
-
const o = this.#normalizeGetOrSet<T>(a, b, c);
|
|
1035
|
+
const o = this.#normalizeGetOrSet<T>(a, b, c, started);
|
|
763
1036
|
const prefixed = this.#prefixKey(o.key);
|
|
764
1037
|
|
|
765
1038
|
const entry = await this.#readEntry<T>(prefixed);
|
|
@@ -769,23 +1042,35 @@ export class CacheManager {
|
|
|
769
1042
|
value: entry.value,
|
|
770
1043
|
store: this.#name,
|
|
771
1044
|
graced: false,
|
|
1045
|
+
duration: this.#since(started),
|
|
772
1046
|
});
|
|
773
1047
|
return entry.value;
|
|
774
1048
|
}
|
|
775
1049
|
|
|
776
1050
|
const hasStale = entry?.stale === true && o.graceSeconds > 0;
|
|
777
1051
|
const staleValue = hasStale ? entry.value : undefined;
|
|
1052
|
+
const staleTags = hasStale ? (entry.tags ?? []) : [];
|
|
778
1053
|
|
|
779
|
-
|
|
780
|
-
|
|
781
|
-
|
|
782
|
-
|
|
783
|
-
|
|
784
|
-
this.#
|
|
1054
|
+
const record = this.#shared.inflight.get(prefixed);
|
|
1055
|
+
// Joining another caller's factory, rather than running our own.
|
|
1056
|
+
const joined = record !== undefined;
|
|
1057
|
+
let factoryPromise: Promise<FactoryOutcome<T>>;
|
|
1058
|
+
if (record === undefined) {
|
|
1059
|
+
factoryPromise = this.#invokeFactory<T>(
|
|
1060
|
+
prefixed,
|
|
1061
|
+
o,
|
|
1062
|
+
hasStale,
|
|
1063
|
+
staleValue,
|
|
1064
|
+
staleTags,
|
|
1065
|
+
);
|
|
1066
|
+
} else {
|
|
1067
|
+
// The map holds every key's factory, whatever its type; what the
|
|
1068
|
+
// leader computes for this key is what this caller reads.
|
|
1069
|
+
factoryPromise = record.promise.then((value) => ({
|
|
1070
|
+
value: claimed<T>(value),
|
|
1071
|
+
fresh: false,
|
|
1072
|
+
}));
|
|
785
1073
|
}
|
|
786
|
-
// Single-flight join point: the shared map is heterogeneous (many T), so
|
|
787
|
-
// this generic re-assertion is unavoidable (mirrors echo <=0.1.5).
|
|
788
|
-
const factoryPromise = record.promise as Promise<T>;
|
|
789
1074
|
|
|
790
1075
|
if (hasStale && staleValue !== undefined) {
|
|
791
1076
|
// Stale-while-revalidate: serve stale up to the soft timeout (default 0
|
|
@@ -802,21 +1087,34 @@ export class CacheManager {
|
|
|
802
1087
|
value: staleValue,
|
|
803
1088
|
store: this.#name,
|
|
804
1089
|
graced: true,
|
|
1090
|
+
duration: this.#since(started),
|
|
805
1091
|
});
|
|
806
1092
|
return staleValue;
|
|
807
1093
|
}
|
|
808
|
-
return result;
|
|
1094
|
+
return this.#settled(o, result, !joined);
|
|
809
1095
|
}
|
|
810
1096
|
|
|
811
|
-
|
|
812
|
-
|
|
1097
|
+
// A joiner waits at most `lockTimeout` for the leader, stale value or
|
|
1098
|
+
// not, as upstream bounds its lock acquisition either way. It was read
|
|
1099
|
+
// on the stale path only, so behind a factory that hung every caller
|
|
1100
|
+
// for the key waited forever. The leader is not bound by it: it holds
|
|
1101
|
+
// the lock, and `hardTimeout` is what bounds its factory.
|
|
1102
|
+
const lockMs = joined ? o.lockTimeoutMs : undefined;
|
|
1103
|
+
const hardMs = o.hardTimeoutMs;
|
|
1104
|
+
if (lockMs !== undefined && (hardMs === undefined || lockMs < hardMs)) {
|
|
1105
|
+
const result = await withTimeout(factoryPromise, lockMs);
|
|
1106
|
+
if (result === TIMEOUT) throw new LockTimeoutError(o.key, lockMs);
|
|
1107
|
+
return this.#settled(o, result, !joined);
|
|
1108
|
+
}
|
|
1109
|
+
if (hardMs !== undefined) {
|
|
1110
|
+
const result = await withTimeout(factoryPromise, hardMs);
|
|
813
1111
|
if (result === TIMEOUT) {
|
|
814
|
-
throw new TimeoutError(o.key,
|
|
1112
|
+
throw new TimeoutError(o.key, hardMs);
|
|
815
1113
|
}
|
|
816
|
-
return result;
|
|
1114
|
+
return this.#settled(o, result, !joined);
|
|
817
1115
|
}
|
|
818
1116
|
|
|
819
|
-
return factoryPromise;
|
|
1117
|
+
return this.#settled(o, await factoryPromise, !joined);
|
|
820
1118
|
}
|
|
821
1119
|
|
|
822
1120
|
/** Like {@link getOrSet} but the stored value never expires (bento `getOrSetForever`). */
|