@c9up/echo 0.2.4 → 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 +11 -2
- package/dist/CacheManager.d.ts.map +1 -1
- package/dist/CacheManager.js +222 -29
- package/dist/CacheManager.js.map +1 -1
- package/dist/StoreManager.d.ts +10 -2
- package/dist/StoreManager.d.ts.map +1 -1
- package/dist/StoreManager.js +41 -7
- package/dist/StoreManager.js.map +1 -1
- package/dist/drivers/MemoryDriver.d.ts +2 -1
- package/dist/drivers/MemoryDriver.d.ts.map +1 -1
- package/dist/drivers/MemoryDriver.js +19 -16
- package/dist/drivers/MemoryDriver.js.map +1 -1
- package/dist/drivers/RedisDriver.d.ts +2 -0
- package/dist/drivers/RedisDriver.d.ts.map +1 -1
- package/dist/drivers/RedisDriver.js +29 -5
- package/dist/drivers/RedisDriver.js.map +1 -1
- package/dist/quasar.d.ts.map +1 -1
- package/dist/quasar.js +80 -14
- package/dist/quasar.js.map +1 -1
- package/dist/types.d.ts +32 -1
- package/dist/types.d.ts.map +1 -1
- package/dist/vendor/quasarConnection.d.ts +18 -0
- package/dist/vendor/quasarConnection.d.ts.map +1 -1
- package/dist/vendor/quasarConnection.js +20 -0
- package/dist/vendor/quasarConnection.js.map +1 -1
- package/package.json +1 -1
- package/src/CacheManager.ts +256 -34
- package/src/StoreManager.ts +48 -7
- package/src/drivers/MemoryDriver.ts +23 -16
- package/src/drivers/RedisDriver.ts +31 -5
- package/src/quasar.ts +103 -24
- package/src/types.ts +33 -5
- package/src/vendor/quasarConnection.ts +21 -0
package/src/CacheManager.ts
CHANGED
|
@@ -83,6 +83,32 @@ function resolveMs(duration: Duration | undefined): number | undefined {
|
|
|
83
83
|
return Math.min(seconds * 1000, MAX_TIMER_MS);
|
|
84
84
|
}
|
|
85
85
|
|
|
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
|
+
}
|
|
94
|
+
|
|
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;
|
|
110
|
+
}
|
|
111
|
+
|
|
86
112
|
const TIMEOUT: unique symbol = Symbol("echo.timeout");
|
|
87
113
|
|
|
88
114
|
function withTimeout<T>(
|
|
@@ -120,6 +146,12 @@ export interface CacheConfig {
|
|
|
120
146
|
ttl?: Duration;
|
|
121
147
|
/** Default grace period (stale-while-revalidate) as a {@link Duration}. */
|
|
122
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;
|
|
123
155
|
/** Default soft timeout for `getOrSet` (return stale if the factory is slower). */
|
|
124
156
|
timeout?: Duration;
|
|
125
157
|
/** Default hard timeout for `getOrSet`. */
|
|
@@ -128,10 +160,17 @@ export interface CacheConfig {
|
|
|
128
160
|
lockTimeout?: Duration;
|
|
129
161
|
/** Store name reported in events (default `"default"`). */
|
|
130
162
|
name?: string;
|
|
131
|
-
/** Optional event emitter (`cache:hit` / `miss` / `written` / `deleted` / `cleared`). */
|
|
163
|
+
/** Optional event emitter (`cache:hit` / `miss` / `written` / `deleted` / `cleared` / `expire`). */
|
|
132
164
|
emitter?: CacheEmitter;
|
|
133
165
|
}
|
|
134
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
|
+
|
|
135
174
|
/** Shared single-flight state — one map per store, threaded through namespaces. */
|
|
136
175
|
interface SharedState {
|
|
137
176
|
inflight: Map<string, { promise: Promise<unknown> }>;
|
|
@@ -142,11 +181,14 @@ interface NormalizedGetOrSet<T> {
|
|
|
142
181
|
factory: Factory<T>;
|
|
143
182
|
ttlSeconds: number;
|
|
144
183
|
graceSeconds: number;
|
|
184
|
+
graceBackoffSeconds: number;
|
|
145
185
|
timeoutMs: number | undefined;
|
|
146
186
|
hardTimeoutMs: number | undefined;
|
|
147
187
|
lockTimeoutMs: number | undefined;
|
|
148
188
|
tags: string[];
|
|
149
189
|
onFactoryError?: (error: FactoryError) => void;
|
|
190
|
+
/** `performance.now()` when the call came in: what its events time from. */
|
|
191
|
+
started: number;
|
|
150
192
|
}
|
|
151
193
|
|
|
152
194
|
/** The slice of `CacheStoreManager` a store it built needs to reach back into. */
|
|
@@ -161,6 +203,7 @@ export class CacheManager {
|
|
|
161
203
|
#prefix: string;
|
|
162
204
|
#defaultTtl: number;
|
|
163
205
|
#defaultGrace: Duration | undefined;
|
|
206
|
+
#defaultGraceBackoff: Duration | undefined;
|
|
164
207
|
#defaultTimeout: Duration | undefined;
|
|
165
208
|
#defaultHardTimeout: Duration | undefined;
|
|
166
209
|
#defaultLockTimeout: Duration | undefined;
|
|
@@ -178,6 +221,7 @@ export class CacheManager {
|
|
|
178
221
|
"cache:written": new Set(),
|
|
179
222
|
"cache:deleted": new Set(),
|
|
180
223
|
"cache:cleared": new Set(),
|
|
224
|
+
"cache:expire": new Set(),
|
|
181
225
|
};
|
|
182
226
|
#shared: SharedState;
|
|
183
227
|
/**
|
|
@@ -199,6 +243,7 @@ export class CacheManager {
|
|
|
199
243
|
this.#prefix = config?.prefix ?? "";
|
|
200
244
|
this.#defaultTtl = resolveTtlSeconds(config?.ttl, 3600);
|
|
201
245
|
this.#defaultGrace = config?.grace;
|
|
246
|
+
this.#defaultGraceBackoff = config?.graceBackoff;
|
|
202
247
|
this.#defaultTimeout = config?.timeout;
|
|
203
248
|
this.#defaultHardTimeout = config?.hardTimeout;
|
|
204
249
|
this.#defaultLockTimeout = config?.lockTimeout;
|
|
@@ -226,6 +271,11 @@ export class CacheManager {
|
|
|
226
271
|
return tags.map((tag) => this.#prefixKey(tag));
|
|
227
272
|
}
|
|
228
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
|
+
|
|
229
279
|
#emit<E extends keyof CacheEventMap>(
|
|
230
280
|
event: E,
|
|
231
281
|
payload: CacheEventMap[E],
|
|
@@ -486,6 +536,7 @@ export class CacheManager {
|
|
|
486
536
|
async get<T = unknown>(
|
|
487
537
|
keyOrOptions: string | GetOptions<T>,
|
|
488
538
|
): Promise<T | undefined> {
|
|
539
|
+
const started = performance.now();
|
|
489
540
|
await this.#whenConnected();
|
|
490
541
|
const key =
|
|
491
542
|
typeof keyOrOptions === "string" ? keyOrOptions : keyOrOptions.key;
|
|
@@ -503,6 +554,7 @@ export class CacheManager {
|
|
|
503
554
|
value: entry.value,
|
|
504
555
|
store: this.#name,
|
|
505
556
|
graced: false,
|
|
557
|
+
duration: this.#since(started),
|
|
506
558
|
});
|
|
507
559
|
return entry.value;
|
|
508
560
|
}
|
|
@@ -512,11 +564,16 @@ export class CacheManager {
|
|
|
512
564
|
value: entry.value,
|
|
513
565
|
store: this.#name,
|
|
514
566
|
graced: true,
|
|
567
|
+
duration: this.#since(started),
|
|
515
568
|
});
|
|
516
569
|
return entry.value;
|
|
517
570
|
}
|
|
518
571
|
|
|
519
|
-
this.#emit("cache:miss", {
|
|
572
|
+
this.#emit("cache:miss", {
|
|
573
|
+
key,
|
|
574
|
+
store: this.#name,
|
|
575
|
+
duration: this.#since(started),
|
|
576
|
+
});
|
|
520
577
|
if (defaultValue !== undefined) {
|
|
521
578
|
return defaultValue instanceof Function ? defaultValue() : defaultValue;
|
|
522
579
|
}
|
|
@@ -537,6 +594,7 @@ export class CacheManager {
|
|
|
537
594
|
value?: unknown,
|
|
538
595
|
ttlSeconds?: number,
|
|
539
596
|
): Promise<void> {
|
|
597
|
+
const started = performance.now();
|
|
540
598
|
await this.#whenConnected();
|
|
541
599
|
let key: string;
|
|
542
600
|
let val: unknown;
|
|
@@ -560,7 +618,13 @@ export class CacheManager {
|
|
|
560
618
|
tags = keyOrOptions.tags ?? [];
|
|
561
619
|
}
|
|
562
620
|
await this.#writeValue(this.#prefixKey(key), val, ttl, graceSeconds, tags);
|
|
563
|
-
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
|
+
});
|
|
564
628
|
}
|
|
565
629
|
|
|
566
630
|
/** Set a value that never expires (bento `setForever`). */
|
|
@@ -573,11 +637,16 @@ export class CacheManager {
|
|
|
573
637
|
delete(key: string): Promise<boolean>;
|
|
574
638
|
delete(options: DeleteOptions): Promise<boolean>;
|
|
575
639
|
async delete(keyOrOptions: string | DeleteOptions): Promise<boolean> {
|
|
640
|
+
const started = performance.now();
|
|
576
641
|
await this.#whenConnected();
|
|
577
642
|
const key =
|
|
578
643
|
typeof keyOrOptions === "string" ? keyOrOptions : keyOrOptions.key;
|
|
579
644
|
const deleted = await this.#driver.delete(this.#prefixKey(key));
|
|
580
|
-
this.#emit("cache:deleted", {
|
|
645
|
+
this.#emit("cache:deleted", {
|
|
646
|
+
key,
|
|
647
|
+
store: this.#name,
|
|
648
|
+
duration: this.#since(started),
|
|
649
|
+
});
|
|
581
650
|
return deleted;
|
|
582
651
|
}
|
|
583
652
|
|
|
@@ -591,8 +660,13 @@ export class CacheManager {
|
|
|
591
660
|
: keysOrOptions.keys;
|
|
592
661
|
let all = true;
|
|
593
662
|
for (const key of keys) {
|
|
663
|
+
const started = performance.now();
|
|
594
664
|
const ok = await this.#driver.delete(this.#prefixKey(key));
|
|
595
|
-
this.#emit("cache:deleted", {
|
|
665
|
+
this.#emit("cache:deleted", {
|
|
666
|
+
key,
|
|
667
|
+
store: this.#name,
|
|
668
|
+
duration: this.#since(started),
|
|
669
|
+
});
|
|
596
670
|
if (!ok) all = false;
|
|
597
671
|
}
|
|
598
672
|
return all;
|
|
@@ -614,7 +688,10 @@ export class CacheManager {
|
|
|
614
688
|
return !(await this.has(key));
|
|
615
689
|
}
|
|
616
690
|
|
|
617
|
-
/**
|
|
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
|
+
*/
|
|
618
695
|
async pull<T = unknown>(key: string): Promise<T | undefined> {
|
|
619
696
|
await this.#whenConnected();
|
|
620
697
|
const value = await this.get<T>(key);
|
|
@@ -627,6 +704,7 @@ export class CacheManager {
|
|
|
627
704
|
* window (bento `expire`). Without grace this is equivalent to a delete.
|
|
628
705
|
*/
|
|
629
706
|
async expire(keyOrOptions: string | ExpireOptions): Promise<boolean> {
|
|
707
|
+
const started = performance.now();
|
|
630
708
|
await this.#whenConnected();
|
|
631
709
|
const key =
|
|
632
710
|
typeof keyOrOptions === "string" ? keyOrOptions : keyOrOptions.key;
|
|
@@ -634,18 +712,33 @@ export class CacheManager {
|
|
|
634
712
|
const graceSeconds = resolveTtlSeconds(this.#defaultGrace, 0);
|
|
635
713
|
const entry = await this.#readEntry<unknown>(prefixed);
|
|
636
714
|
if (entry === null) return false;
|
|
715
|
+
let expired: boolean;
|
|
637
716
|
if (graceSeconds > 0 && this.#driver.setEntry) {
|
|
638
717
|
// Mark the entry stale RIGHT NOW (logical expiry one ms in the past) while
|
|
639
718
|
// keeping it physically for the grace window. A positive `ttlSeconds`
|
|
640
719
|
// would leave a brief fresh window during which the value is still served
|
|
641
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.
|
|
642
725
|
await this.#driver.setEntry(prefixed, entry.value, {
|
|
643
726
|
expiresAt: Date.now() - 1,
|
|
644
727
|
graceSeconds,
|
|
728
|
+
tags: entry.tags ?? [],
|
|
645
729
|
});
|
|
646
|
-
|
|
730
|
+
expired = true;
|
|
731
|
+
} else {
|
|
732
|
+
expired = await this.#driver.delete(prefixed);
|
|
647
733
|
}
|
|
648
|
-
|
|
734
|
+
if (expired) {
|
|
735
|
+
this.#emit("cache:expire", {
|
|
736
|
+
key,
|
|
737
|
+
store: this.#name,
|
|
738
|
+
duration: this.#since(started),
|
|
739
|
+
});
|
|
740
|
+
}
|
|
741
|
+
return expired;
|
|
649
742
|
}
|
|
650
743
|
|
|
651
744
|
/**
|
|
@@ -657,11 +750,15 @@ export class CacheManager {
|
|
|
657
750
|
* handing the driver the prefix.
|
|
658
751
|
*/
|
|
659
752
|
async clear(): Promise<void> {
|
|
753
|
+
const started = performance.now();
|
|
660
754
|
await this.#whenConnected();
|
|
661
755
|
// The separator is part of it: `tenant-a` must not take `tenant-abc`
|
|
662
756
|
// with it, and every key under this view is written `<prefix>:<key>`.
|
|
663
757
|
await this.#driver.flush(this.#prefix ? `${this.#prefix}:` : undefined);
|
|
664
|
-
this.#emit("cache:cleared", {
|
|
758
|
+
this.#emit("cache:cleared", {
|
|
759
|
+
store: this.#name,
|
|
760
|
+
duration: this.#since(started),
|
|
761
|
+
});
|
|
665
762
|
}
|
|
666
763
|
|
|
667
764
|
// ---- tags ------------------------------------------------------------
|
|
@@ -673,15 +770,17 @@ export class CacheManager {
|
|
|
673
770
|
tags: string[],
|
|
674
771
|
ttlSeconds?: number,
|
|
675
772
|
): Promise<void> {
|
|
773
|
+
const started = performance.now();
|
|
676
774
|
await this.#whenConnected();
|
|
677
|
-
|
|
678
|
-
|
|
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,
|
|
679
779
|
value,
|
|
680
|
-
|
|
681
|
-
|
|
682
|
-
|
|
683
|
-
);
|
|
684
|
-
this.#emit("cache:written", { key, value, store: this.#name });
|
|
780
|
+
store: this.#name,
|
|
781
|
+
ttl: reportedTtl(ttl),
|
|
782
|
+
duration: this.#since(started),
|
|
783
|
+
});
|
|
685
784
|
}
|
|
686
785
|
|
|
687
786
|
/** Invalidate all entries carrying any of the given tags (bento `deleteByTag`). */
|
|
@@ -723,6 +822,7 @@ export class CacheManager {
|
|
|
723
822
|
prefix: this.#prefix ? `${this.#prefix}:${ns}` : ns,
|
|
724
823
|
ttl: this.#defaultTtl,
|
|
725
824
|
grace: this.#defaultGrace,
|
|
825
|
+
graceBackoff: this.#defaultGraceBackoff,
|
|
726
826
|
timeout: this.#defaultTimeout,
|
|
727
827
|
hardTimeout: this.#defaultHardTimeout,
|
|
728
828
|
lockTimeout: this.#defaultLockTimeout,
|
|
@@ -739,6 +839,7 @@ export class CacheManager {
|
|
|
739
839
|
a: string | GetOrSetOptions<T>,
|
|
740
840
|
b: number | undefined,
|
|
741
841
|
c: Factory<T> | undefined,
|
|
842
|
+
started: number,
|
|
742
843
|
): NormalizedGetOrSet<T> {
|
|
743
844
|
if (typeof a === "string") {
|
|
744
845
|
if (typeof c !== "function") {
|
|
@@ -751,39 +852,68 @@ export class CacheManager {
|
|
|
751
852
|
factory: c,
|
|
752
853
|
ttlSeconds: resolveTtlSeconds(b, this.#defaultTtl),
|
|
753
854
|
graceSeconds: resolveTtlSeconds(this.#defaultGrace, 0),
|
|
855
|
+
graceBackoffSeconds: resolveBackoffSeconds(this.#defaultGraceBackoff),
|
|
754
856
|
timeoutMs: resolveMs(this.#defaultTimeout),
|
|
755
857
|
hardTimeoutMs: resolveMs(this.#defaultHardTimeout),
|
|
756
858
|
lockTimeoutMs: resolveMs(this.#defaultLockTimeout),
|
|
757
859
|
tags: [],
|
|
860
|
+
started,
|
|
758
861
|
};
|
|
759
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
|
+
}
|
|
760
871
|
return {
|
|
761
872
|
key: a.key,
|
|
762
873
|
factory: a.factory,
|
|
763
874
|
ttlSeconds: resolveTtlSeconds(a.ttl, this.#defaultTtl),
|
|
764
875
|
graceSeconds: resolveTtlSeconds(a.grace ?? this.#defaultGrace, 0),
|
|
876
|
+
graceBackoffSeconds: resolveBackoffSeconds(
|
|
877
|
+
a.graceBackoff === undefined
|
|
878
|
+
? this.#defaultGraceBackoff
|
|
879
|
+
: a.graceBackoff,
|
|
880
|
+
),
|
|
765
881
|
timeoutMs: resolveMs(a.timeout ?? this.#defaultTimeout),
|
|
766
882
|
hardTimeoutMs: resolveMs(a.hardTimeout ?? this.#defaultHardTimeout),
|
|
767
883
|
lockTimeoutMs: resolveMs(a.lockTimeout ?? this.#defaultLockTimeout),
|
|
768
884
|
tags: a.tags ?? [],
|
|
769
885
|
onFactoryError: a.onFactoryError,
|
|
886
|
+
started,
|
|
770
887
|
};
|
|
771
888
|
}
|
|
772
889
|
|
|
773
890
|
/**
|
|
774
|
-
* Run
|
|
775
|
-
* fresh value on success; on
|
|
776
|
-
*
|
|
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.
|
|
777
896
|
*/
|
|
778
897
|
#invokeFactory<T>(
|
|
779
898
|
prefixed: string,
|
|
780
899
|
o: NormalizedGetOrSet<T>,
|
|
781
900
|
hasStale: boolean,
|
|
782
901
|
staleValue: T | undefined,
|
|
783
|
-
|
|
784
|
-
|
|
902
|
+
staleTags: string[],
|
|
903
|
+
): Promise<FactoryOutcome<T>> {
|
|
904
|
+
const run = async (): Promise<FactoryOutcome<T>> => {
|
|
785
905
|
try {
|
|
786
|
-
|
|
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();
|
|
787
917
|
await this.#writeValue(
|
|
788
918
|
prefixed,
|
|
789
919
|
value,
|
|
@@ -795,17 +925,102 @@ export class CacheManager {
|
|
|
795
925
|
key: o.key,
|
|
796
926
|
value,
|
|
797
927
|
store: this.#name,
|
|
928
|
+
ttl: reportedTtl(o.ttlSeconds),
|
|
929
|
+
duration: this.#since(writing),
|
|
798
930
|
});
|
|
799
|
-
return value;
|
|
931
|
+
return { value, fresh: true };
|
|
800
932
|
} catch (error) {
|
|
801
933
|
o.onFactoryError?.(new FactoryError(o.key, error, hasStale));
|
|
802
|
-
if (hasStale && staleValue !== undefined)
|
|
934
|
+
if (hasStale && staleValue !== undefined) {
|
|
935
|
+
await this.#applyGraceBackoff(prefixed, staleValue, staleTags, o);
|
|
936
|
+
return { value: staleValue, fresh: false };
|
|
937
|
+
}
|
|
803
938
|
throw error;
|
|
804
939
|
} finally {
|
|
805
|
-
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
|
+
}
|
|
806
944
|
}
|
|
807
945
|
};
|
|
808
|
-
|
|
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;
|
|
809
1024
|
}
|
|
810
1025
|
|
|
811
1026
|
getOrSet<T>(key: string, ttlSeconds: number, factory: Factory<T>): Promise<T>;
|
|
@@ -815,8 +1030,9 @@ export class CacheManager {
|
|
|
815
1030
|
b?: number,
|
|
816
1031
|
c?: Factory<T>,
|
|
817
1032
|
): Promise<T> {
|
|
1033
|
+
const started = performance.now();
|
|
818
1034
|
await this.#whenConnected();
|
|
819
|
-
const o = this.#normalizeGetOrSet<T>(a, b, c);
|
|
1035
|
+
const o = this.#normalizeGetOrSet<T>(a, b, c, started);
|
|
820
1036
|
const prefixed = this.#prefixKey(o.key);
|
|
821
1037
|
|
|
822
1038
|
const entry = await this.#readEntry<T>(prefixed);
|
|
@@ -826,29 +1042,34 @@ export class CacheManager {
|
|
|
826
1042
|
value: entry.value,
|
|
827
1043
|
store: this.#name,
|
|
828
1044
|
graced: false,
|
|
1045
|
+
duration: this.#since(started),
|
|
829
1046
|
});
|
|
830
1047
|
return entry.value;
|
|
831
1048
|
}
|
|
832
1049
|
|
|
833
1050
|
const hasStale = entry?.stale === true && o.graceSeconds > 0;
|
|
834
1051
|
const staleValue = hasStale ? entry.value : undefined;
|
|
1052
|
+
const staleTags = hasStale ? (entry.tags ?? []) : [];
|
|
835
1053
|
|
|
836
1054
|
const record = this.#shared.inflight.get(prefixed);
|
|
837
1055
|
// Joining another caller's factory, rather than running our own.
|
|
838
1056
|
const joined = record !== undefined;
|
|
839
|
-
let factoryPromise: Promise<T
|
|
1057
|
+
let factoryPromise: Promise<FactoryOutcome<T>>;
|
|
840
1058
|
if (record === undefined) {
|
|
841
1059
|
factoryPromise = this.#invokeFactory<T>(
|
|
842
1060
|
prefixed,
|
|
843
1061
|
o,
|
|
844
1062
|
hasStale,
|
|
845
1063
|
staleValue,
|
|
1064
|
+
staleTags,
|
|
846
1065
|
);
|
|
847
|
-
this.#shared.inflight.set(prefixed, { promise: factoryPromise });
|
|
848
1066
|
} else {
|
|
849
1067
|
// The map holds every key's factory, whatever its type; what the
|
|
850
1068
|
// leader computes for this key is what this caller reads.
|
|
851
|
-
factoryPromise = record.promise.then((value) =>
|
|
1069
|
+
factoryPromise = record.promise.then((value) => ({
|
|
1070
|
+
value: claimed<T>(value),
|
|
1071
|
+
fresh: false,
|
|
1072
|
+
}));
|
|
852
1073
|
}
|
|
853
1074
|
|
|
854
1075
|
if (hasStale && staleValue !== undefined) {
|
|
@@ -866,10 +1087,11 @@ export class CacheManager {
|
|
|
866
1087
|
value: staleValue,
|
|
867
1088
|
store: this.#name,
|
|
868
1089
|
graced: true,
|
|
1090
|
+
duration: this.#since(started),
|
|
869
1091
|
});
|
|
870
1092
|
return staleValue;
|
|
871
1093
|
}
|
|
872
|
-
return result;
|
|
1094
|
+
return this.#settled(o, result, !joined);
|
|
873
1095
|
}
|
|
874
1096
|
|
|
875
1097
|
// A joiner waits at most `lockTimeout` for the leader, stale value or
|
|
@@ -882,17 +1104,17 @@ export class CacheManager {
|
|
|
882
1104
|
if (lockMs !== undefined && (hardMs === undefined || lockMs < hardMs)) {
|
|
883
1105
|
const result = await withTimeout(factoryPromise, lockMs);
|
|
884
1106
|
if (result === TIMEOUT) throw new LockTimeoutError(o.key, lockMs);
|
|
885
|
-
return result;
|
|
1107
|
+
return this.#settled(o, result, !joined);
|
|
886
1108
|
}
|
|
887
1109
|
if (hardMs !== undefined) {
|
|
888
1110
|
const result = await withTimeout(factoryPromise, hardMs);
|
|
889
1111
|
if (result === TIMEOUT) {
|
|
890
1112
|
throw new TimeoutError(o.key, hardMs);
|
|
891
1113
|
}
|
|
892
|
-
return result;
|
|
1114
|
+
return this.#settled(o, result, !joined);
|
|
893
1115
|
}
|
|
894
1116
|
|
|
895
|
-
return factoryPromise;
|
|
1117
|
+
return this.#settled(o, await factoryPromise, !joined);
|
|
896
1118
|
}
|
|
897
1119
|
|
|
898
1120
|
/** Like {@link getOrSet} but the stored value never expires (bento `getOrSetForever`). */
|
package/src/StoreManager.ts
CHANGED
|
@@ -57,6 +57,8 @@ export interface StoreConfig {
|
|
|
57
57
|
*/
|
|
58
58
|
ttl?: Duration;
|
|
59
59
|
grace?: Duration;
|
|
60
|
+
/** How long a stale value stands in after its factory failed (default `'10s'`). */
|
|
61
|
+
graceBackoff?: Duration;
|
|
60
62
|
timeout?: Duration;
|
|
61
63
|
hardTimeout?: Duration;
|
|
62
64
|
lockTimeout?: Duration;
|
|
@@ -169,6 +171,16 @@ export function store(options?: Omit<StoreConfig, "driver">): Store {
|
|
|
169
171
|
return new Store(options);
|
|
170
172
|
}
|
|
171
173
|
|
|
174
|
+
/** Either accepted form of a store: a {@link Store} builder, or `{ driver, … }`. */
|
|
175
|
+
function isStoreDeclaration(value: unknown): value is StoreConfig | Store {
|
|
176
|
+
if (value instanceof Store) return true;
|
|
177
|
+
return (
|
|
178
|
+
typeof value === "object" &&
|
|
179
|
+
value !== null &&
|
|
180
|
+
typeof Reflect.get(value, "driver") === "function"
|
|
181
|
+
);
|
|
182
|
+
}
|
|
183
|
+
|
|
172
184
|
/** Normalise either accepted form to the one the manager reads. */
|
|
173
185
|
function entryOf(config: StoreConfig | Store): StoreConfig {
|
|
174
186
|
return config instanceof Store ? config.entry() : config;
|
|
@@ -251,6 +263,7 @@ export class CacheStoreManager {
|
|
|
251
263
|
"cache:written": new Set(),
|
|
252
264
|
"cache:deleted": new Set(),
|
|
253
265
|
"cache:cleared": new Set(),
|
|
266
|
+
"cache:expire": new Set(),
|
|
254
267
|
};
|
|
255
268
|
|
|
256
269
|
constructor(config: MultiStoreConfig) {
|
|
@@ -266,11 +279,22 @@ export class CacheStoreManager {
|
|
|
266
279
|
/**
|
|
267
280
|
* A store declared under `name` in the config's OWN keys: a plain lookup
|
|
268
281
|
* would answer `toString` or `constructor` with an Object.prototype member.
|
|
282
|
+
*
|
|
283
|
+
* And one that IS a store. A config is read at runtime, from a file the
|
|
284
|
+
* type checker may never have seen: an own key holding `{}` or `null`
|
|
285
|
+
* passed the lookup, then failed on `cfg.driver(...)` with a bare
|
|
286
|
+
* TypeError, far from the line at fault.
|
|
269
287
|
*/
|
|
270
288
|
#declared(name: string): MultiStoreConfig["stores"][string] | undefined {
|
|
271
|
-
|
|
272
|
-
|
|
273
|
-
|
|
289
|
+
if (!Object.hasOwn(this.#config.stores, name)) return undefined;
|
|
290
|
+
const declared: unknown = this.#config.stores[name];
|
|
291
|
+
if (!isStoreDeclaration(declared)) {
|
|
292
|
+
throw new EchoError(
|
|
293
|
+
"E_ECHO_INVALID_CONFIG",
|
|
294
|
+
`Echo: cache store "${name}" is not a store — declare it with store().useL1Layer(…) or as { driver: drivers.memory() }`,
|
|
295
|
+
);
|
|
296
|
+
}
|
|
297
|
+
return declared;
|
|
274
298
|
}
|
|
275
299
|
|
|
276
300
|
/** The store `use()` answers with no name (upstream `defaultStoreName`). */
|
|
@@ -297,6 +321,7 @@ export class CacheStoreManager {
|
|
|
297
321
|
// The store's own, or the one every store inherits.
|
|
298
322
|
ttl: cfg.ttl ?? this.#config.ttl,
|
|
299
323
|
grace: cfg.grace,
|
|
324
|
+
graceBackoff: cfg.graceBackoff,
|
|
300
325
|
timeout: cfg.timeout,
|
|
301
326
|
hardTimeout: cfg.hardTimeout,
|
|
302
327
|
lockTimeout: cfg.lockTimeout,
|
|
@@ -316,6 +341,7 @@ export class CacheStoreManager {
|
|
|
316
341
|
replay("cache:written");
|
|
317
342
|
replay("cache:deleted");
|
|
318
343
|
replay("cache:cleared");
|
|
344
|
+
replay("cache:expire");
|
|
319
345
|
// So `cache.use('other')` works on whichever store the provider
|
|
320
346
|
// published — upstream's manager is one object that both operates on
|
|
321
347
|
// the default store and reaches the named ones.
|
|
@@ -367,14 +393,29 @@ export class CacheStoreManager {
|
|
|
367
393
|
return this;
|
|
368
394
|
}
|
|
369
395
|
|
|
370
|
-
/**
|
|
396
|
+
/**
|
|
397
|
+
* Every store the config declares, built here if this process has not
|
|
398
|
+
* used it yet. Walking only the built ones skipped a store another
|
|
399
|
+
* process writes to: a maintenance script's `clearAll` left its keys.
|
|
400
|
+
*/
|
|
401
|
+
#everyStore(): CacheManager[] {
|
|
402
|
+
return Object.keys(this.#config.stores).map((name) => this.use(name));
|
|
403
|
+
}
|
|
404
|
+
|
|
405
|
+
/** Clear every configured store (bentocache `clearAll`). */
|
|
371
406
|
async clearAll(): Promise<void> {
|
|
372
|
-
await Promise.all(
|
|
407
|
+
await Promise.all(this.#everyStore().map((m) => m.clear()));
|
|
373
408
|
}
|
|
374
409
|
|
|
375
|
-
/**
|
|
410
|
+
/**
|
|
411
|
+
* Prune expired entries in every configured store (bentocache `prune`).
|
|
412
|
+
*
|
|
413
|
+
* NAMED DEVIATION: upstream's manager prunes the default store only; a
|
|
414
|
+
* store that needs pruning is no less in need of it for not being the
|
|
415
|
+
* default, so every configured one is reached, as `clearAll` does.
|
|
416
|
+
*/
|
|
376
417
|
async prune(): Promise<void> {
|
|
377
|
-
await Promise.all(
|
|
418
|
+
await Promise.all(this.#everyStore().map((m) => m.prune()));
|
|
378
419
|
}
|
|
379
420
|
|
|
380
421
|
/**
|