@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
|
@@ -27,7 +27,8 @@ export interface MemoryDriverOptions {
|
|
|
27
27
|
/**
|
|
28
28
|
* Largest single value, in bytes or as `'1mb'`. A bigger one is not
|
|
29
29
|
* stored, and the key's previous value goes with it. Defaults to
|
|
30
|
-
* `maxSize` when that is set
|
|
30
|
+
* `maxSize` when that is set, and a value over `maxSize` is never stored
|
|
31
|
+
* whatever this says. Needs `serialize`.
|
|
31
32
|
*/
|
|
32
33
|
maxEntrySize?: number | string;
|
|
33
34
|
/**
|
|
@@ -145,22 +146,18 @@ export class MemoryDriver implements TaggableDriver {
|
|
|
145
146
|
}
|
|
146
147
|
|
|
147
148
|
/**
|
|
148
|
-
* Drop entries until the store fits under its
|
|
149
|
+
* Drop the least recently used entries until the store fits under its
|
|
150
|
+
* ceilings: the Map's order, since a read moves its key to the end as a
|
|
151
|
+
* write does.
|
|
149
152
|
*
|
|
150
|
-
*
|
|
151
|
-
*
|
|
152
|
-
*
|
|
153
|
-
*
|
|
153
|
+
* The least recently used, whatever has expired elsewhere in the order.
|
|
154
|
+
* Hunting for expired entries first walked the whole map on every write
|
|
155
|
+
* at the ceiling, a cost proportional to the ceiling a large working set
|
|
156
|
+
* pays on each write; expired entries are the sweep's, and a read drops
|
|
157
|
+
* one it finds. Upstream's LRU evicts the same way.
|
|
154
158
|
*/
|
|
155
159
|
#enforceCeiling(): void {
|
|
156
160
|
if (this.#fits()) return;
|
|
157
|
-
const now = Date.now();
|
|
158
|
-
for (const [key, entry] of this.#store) {
|
|
159
|
-
if (this.#fits()) return;
|
|
160
|
-
if (entry.staleUntil > 0 && entry.staleUntil < now) {
|
|
161
|
-
this.#evict(key, entry);
|
|
162
|
-
}
|
|
163
|
-
}
|
|
164
161
|
for (const [key, entry] of this.#store) {
|
|
165
162
|
if (this.#fits()) return;
|
|
166
163
|
this.#evict(key, entry);
|
|
@@ -282,9 +279,15 @@ export class MemoryDriver implements TaggableDriver {
|
|
|
282
279
|
// previous entry and its tags exactly as they were.
|
|
283
280
|
const stored = this.#serialize ? toJson(value) : value;
|
|
284
281
|
const size = typeof stored === "string" ? Buffer.byteLength(stored) : 0;
|
|
285
|
-
if (
|
|
282
|
+
if (
|
|
283
|
+
(this.#maxEntrySize > 0 && size > this.#maxEntrySize) ||
|
|
284
|
+
(this.#maxSize > 0 && size > this.#maxSize)
|
|
285
|
+
) {
|
|
286
286
|
// Too big to keep. The previous value goes too, as upstream's LRU
|
|
287
|
-
// does: a skipped write must not leave an older value served.
|
|
287
|
+
// does: a skipped write must not leave an older value served. A
|
|
288
|
+
// value over the whole store's bound counts as too big whatever
|
|
289
|
+
// maxEntrySize says: inserted, it evicted every other entry and
|
|
290
|
+
// then itself.
|
|
288
291
|
this.#deleteEntry(key);
|
|
289
292
|
return;
|
|
290
293
|
}
|
|
@@ -326,7 +329,10 @@ export class MemoryDriver implements TaggableDriver {
|
|
|
326
329
|
size,
|
|
327
330
|
});
|
|
328
331
|
this.#size += size;
|
|
329
|
-
|
|
332
|
+
// Indexed BEFORE the ceiling is enforced, so an eviction that takes
|
|
333
|
+
// this very entry untags it. Indexed after, an entry the ceiling had
|
|
334
|
+
// just dropped stayed in its tags' sets, and a later deleteByTag of
|
|
335
|
+
// one of them purged whatever value the key held by then.
|
|
330
336
|
for (const tag of tags) {
|
|
331
337
|
let set = this.#tagIndex.get(tag);
|
|
332
338
|
if (!set) {
|
|
@@ -335,6 +341,7 @@ export class MemoryDriver implements TaggableDriver {
|
|
|
335
341
|
}
|
|
336
342
|
set.add(key);
|
|
337
343
|
}
|
|
344
|
+
this.#enforceCeiling();
|
|
338
345
|
}
|
|
339
346
|
|
|
340
347
|
async set(key: string, value: unknown, ttlSeconds?: number): Promise<void> {
|
|
@@ -17,6 +17,7 @@ import { claimed } from "../claim.js";
|
|
|
17
17
|
import { checkTtlSeconds } from "../duration.js";
|
|
18
18
|
import { EchoError } from "../errors.js";
|
|
19
19
|
import type { CacheEntry, DriverSetOptions, TaggableDriver } from "../types.js";
|
|
20
|
+
import { hasEnded } from "../vendor/quasarConnection.js";
|
|
20
21
|
|
|
21
22
|
/**
|
|
22
23
|
* Minimal Redis client interface, in ioredis' shape — a raw ioredis client
|
|
@@ -33,6 +34,8 @@ export interface RedisClient {
|
|
|
33
34
|
srem(key: string, ...members: string[]): Promise<number>;
|
|
34
35
|
smembers(key: string): Promise<string[]>;
|
|
35
36
|
expire(key: string, seconds: number): Promise<number>;
|
|
37
|
+
/** Drop a key's expiry, so a tag set outlives no less than an immortal member. */
|
|
38
|
+
persist(key: string): Promise<number>;
|
|
36
39
|
ttl(key: string): Promise<number>;
|
|
37
40
|
scan?(
|
|
38
41
|
cursor: string,
|
|
@@ -107,8 +110,18 @@ export class RedisDriver implements TaggableDriver {
|
|
|
107
110
|
/**
|
|
108
111
|
* The client, resolved once. Two commands racing on a cold store must not
|
|
109
112
|
* each open their own connection, so the in-flight promise is shared.
|
|
113
|
+
*
|
|
114
|
+
* Resolved AGAIN once the client it holds has ended for good: quasar
|
|
115
|
+
* retires a connection whose retry strategy gave up and hands out a fresh
|
|
116
|
+
* one, and keeping the dead client made a three-second Redis blip a
|
|
117
|
+
* permanent cache outage. NAMED DEVIATION, better than upstream, whose
|
|
118
|
+
* Redis driver captures `ioConnection` once. A client handed in directly is
|
|
119
|
+
* kept whatever its state.
|
|
110
120
|
*/
|
|
111
121
|
async #client(): Promise<RedisClient> {
|
|
122
|
+
if (typeof this.#source === "function" && hasEnded(this.#resolved)) {
|
|
123
|
+
this.#resolved = undefined;
|
|
124
|
+
}
|
|
112
125
|
if (this.#resolved) return this.#resolved;
|
|
113
126
|
if (typeof this.#source !== "function") {
|
|
114
127
|
this.#resolved = this.#source;
|
|
@@ -392,14 +405,27 @@ export class RedisDriver implements TaggableDriver {
|
|
|
392
405
|
|
|
393
406
|
for (const tag of tags) {
|
|
394
407
|
const tagKey = this.#tagKey(tag);
|
|
408
|
+
// Read BEFORE the SADD. Redis answers -2 for no such key and -1 for
|
|
409
|
+
// a key with no expiry, and a set the SADD has just created reads
|
|
410
|
+
// -1 too: only this order tells a new set from a persistent one.
|
|
411
|
+
const currentTtl = await client.ttl(tagKey);
|
|
395
412
|
if (addedTags.includes(tag)) {
|
|
396
413
|
await client.sadd(tagKey, key);
|
|
397
414
|
}
|
|
398
|
-
|
|
399
|
-
|
|
400
|
-
|
|
401
|
-
|
|
402
|
-
|
|
415
|
+
// A tag set must outlive every member it indexes. It took the TTL
|
|
416
|
+
// of the last member written with one, and an immortal member never
|
|
417
|
+
// cleared that TTL: once the set lapsed, deleteByTag found nobody
|
|
418
|
+
// and the immortal entry kept being served. So an immortal member
|
|
419
|
+
// makes the set persistent, and a finite member never puts an
|
|
420
|
+
// expiry back on a persistent set. A persistent set left holding
|
|
421
|
+
// only lapsed members is emptied by the next deleteByTag of its tag.
|
|
422
|
+
if (physicalTtlSeconds === 0) {
|
|
423
|
+
if (currentTtl >= 0) await client.persist(tagKey);
|
|
424
|
+
} else if (
|
|
425
|
+
currentTtl === -2 ||
|
|
426
|
+
(currentTtl >= 0 && indexTtl > currentTtl)
|
|
427
|
+
) {
|
|
428
|
+
await client.expire(tagKey, indexTtl);
|
|
403
429
|
}
|
|
404
430
|
}
|
|
405
431
|
|
package/src/quasar.ts
CHANGED
|
@@ -20,6 +20,7 @@ import {
|
|
|
20
20
|
import { EchoError } from "./errors.js";
|
|
21
21
|
import {
|
|
22
22
|
hasCommands,
|
|
23
|
+
hasEnded,
|
|
23
24
|
quasarConnection as loadQuasarConnection,
|
|
24
25
|
} from "./vendor/quasarConnection.js";
|
|
25
26
|
|
|
@@ -41,6 +42,7 @@ const REQUIRED = [
|
|
|
41
42
|
"srem",
|
|
42
43
|
"smembers",
|
|
43
44
|
"expire",
|
|
45
|
+
"persist",
|
|
44
46
|
"ttl",
|
|
45
47
|
] as const;
|
|
46
48
|
|
|
@@ -176,21 +178,109 @@ export function quasarBus(options?: {
|
|
|
176
178
|
Promise<(raw: string) => void>
|
|
177
179
|
>();
|
|
178
180
|
|
|
181
|
+
/** What `ready` settled to, so its state can be read. */
|
|
182
|
+
let current: PubSubSource | undefined;
|
|
183
|
+
/**
|
|
184
|
+
* Subscriptions to carry over from a source that ended, taken when the end
|
|
185
|
+
* was noticed. A snapshot, not `opened` itself: a subscribe made after that
|
|
186
|
+
* moment waits on the new source, and waiting on it from here would be
|
|
187
|
+
* waiting on ourselves.
|
|
188
|
+
*/
|
|
189
|
+
let moving:
|
|
190
|
+
| { from: PubSubSource; pending: Array<Promise<(raw: string) => void>> }
|
|
191
|
+
| undefined;
|
|
192
|
+
|
|
193
|
+
/**
|
|
194
|
+
* Listen on `source`, waited on through the callbacks, not on the call's
|
|
195
|
+
* return value: `subscribe` reports a failure rather than rejecting, and
|
|
196
|
+
* newer quasar declares it `void`. This shape is correct against both.
|
|
197
|
+
*/
|
|
198
|
+
const listen = (
|
|
199
|
+
source: PubSubSource,
|
|
200
|
+
wrapper: (raw: string) => void,
|
|
201
|
+
): Promise<void> =>
|
|
202
|
+
new Promise<void>((resolve, reject) => {
|
|
203
|
+
source.subscribe(channel, wrapper, {
|
|
204
|
+
onSubscription: () => resolve(),
|
|
205
|
+
onError: (error) =>
|
|
206
|
+
reject(error instanceof Error ? error : new Error(String(error))),
|
|
207
|
+
});
|
|
208
|
+
});
|
|
209
|
+
|
|
210
|
+
/**
|
|
211
|
+
* Carry every listener over to the connection that replaced an ended one.
|
|
212
|
+
* The subscriptions lived on the dead subscriber socket — quasar drops
|
|
213
|
+
* them on its `end` — so without this the instance kept publishing on the
|
|
214
|
+
* new connection and never heard its peers again: every one served its
|
|
215
|
+
* stale L1 until the TTL ran out.
|
|
216
|
+
*/
|
|
217
|
+
const move = async (
|
|
218
|
+
from: PubSubSource,
|
|
219
|
+
to: PubSubSource,
|
|
220
|
+
pending: Array<Promise<(raw: string) => void>>,
|
|
221
|
+
): Promise<void> => {
|
|
222
|
+
for (const opening of pending) {
|
|
223
|
+
let wrapper: (raw: string) => void;
|
|
224
|
+
try {
|
|
225
|
+
wrapper = await opening;
|
|
226
|
+
} catch {
|
|
227
|
+
// Never subscribed: its own caller already saw the rejection.
|
|
228
|
+
continue;
|
|
229
|
+
}
|
|
230
|
+
await listen(to, wrapper);
|
|
231
|
+
try {
|
|
232
|
+
// Named, as everywhere else: the old connection may be shared.
|
|
233
|
+
await from.unsubscribe?.(channel, wrapper);
|
|
234
|
+
} catch {
|
|
235
|
+
// The ended socket refuses; nothing listens on it any more anyway.
|
|
236
|
+
}
|
|
237
|
+
}
|
|
238
|
+
};
|
|
239
|
+
|
|
179
240
|
const manager = (): Promise<PubSubSource> => {
|
|
241
|
+
// Re-resolved once the source has ended for good: quasar retires a
|
|
242
|
+
// connection whose retry strategy gave up and hands out a fresh one,
|
|
243
|
+
// and keeping the dead one failed every publish with "Connection is
|
|
244
|
+
// closed." until restart. NAMED DEVIATION, better than upstream, whose
|
|
245
|
+
// bus keeps the client it was built with.
|
|
246
|
+
if (current !== undefined && hasEnded(current)) {
|
|
247
|
+
moving ??= { from: current, pending: [...opened.values()] };
|
|
248
|
+
current = undefined;
|
|
249
|
+
ready = undefined;
|
|
250
|
+
}
|
|
180
251
|
ready ??= loadQuasar(
|
|
181
252
|
`the cache bus asks for the "${options?.connection ?? "default"}" quasar connection`,
|
|
182
|
-
)
|
|
183
|
-
|
|
184
|
-
|
|
185
|
-
|
|
186
|
-
|
|
187
|
-
|
|
188
|
-
|
|
189
|
-
|
|
190
|
-
|
|
191
|
-
|
|
192
|
-
|
|
193
|
-
|
|
253
|
+
)
|
|
254
|
+
.then((loaded) => {
|
|
255
|
+
const source = isConnectionSource(loaded)
|
|
256
|
+
? loaded.connection(options?.connection)
|
|
257
|
+
: loaded;
|
|
258
|
+
if (!isPubSubSource(source)) {
|
|
259
|
+
throw new EchoError(
|
|
260
|
+
"E_ECHO_INCOMPLETE_CONNECTION",
|
|
261
|
+
"Echo: the quasar connection does not expose publish()/subscribe()",
|
|
262
|
+
);
|
|
263
|
+
}
|
|
264
|
+
return source;
|
|
265
|
+
})
|
|
266
|
+
.then(async (source) => {
|
|
267
|
+
// A move that fails leaves `moving` set, so the next call — which
|
|
268
|
+
// resolves again, since this one rejects — tries it again.
|
|
269
|
+
if (moving !== undefined && moving.from !== source) {
|
|
270
|
+
await move(moving.from, source, moving.pending);
|
|
271
|
+
}
|
|
272
|
+
moving = undefined;
|
|
273
|
+
current = source;
|
|
274
|
+
return source;
|
|
275
|
+
})
|
|
276
|
+
// Forgotten on failure, as the Redis driver forgets its client:
|
|
277
|
+
// kept, one rejection (quasar's provider not booted yet when an
|
|
278
|
+
// earlier provider wrote to a tiered store) was replayed by every
|
|
279
|
+
// later publish and subscribe for the life of the process.
|
|
280
|
+
.catch((error: unknown) => {
|
|
281
|
+
ready = undefined;
|
|
282
|
+
throw error;
|
|
283
|
+
});
|
|
194
284
|
return ready;
|
|
195
285
|
};
|
|
196
286
|
|
|
@@ -224,18 +314,7 @@ export function quasarBus(options?: {
|
|
|
224
314
|
// quietly incoherent.
|
|
225
315
|
const attempt = (async (): Promise<(raw: string) => void> => {
|
|
226
316
|
const source = await manager();
|
|
227
|
-
|
|
228
|
-
// `subscribe` reports a failure rather than rejecting, and newer
|
|
229
|
-
// quasar declares it `void`. This shape is correct against both.
|
|
230
|
-
await new Promise<void>((resolve, reject) => {
|
|
231
|
-
source.subscribe(channel, wrapper, {
|
|
232
|
-
onSubscription: () => resolve(),
|
|
233
|
-
onError: (error) => {
|
|
234
|
-
opened.delete(handler);
|
|
235
|
-
reject(error instanceof Error ? error : new Error(String(error)));
|
|
236
|
-
},
|
|
237
|
-
});
|
|
238
|
-
});
|
|
317
|
+
await listen(source, wrapper);
|
|
239
318
|
return wrapper;
|
|
240
319
|
})();
|
|
241
320
|
opened.set(handler, attempt);
|
package/src/types.ts
CHANGED
|
@@ -147,6 +147,12 @@ export interface GetOrSetOptions<T> {
|
|
|
147
147
|
factory: Factory<T>;
|
|
148
148
|
ttl?: Duration;
|
|
149
149
|
grace?: Duration;
|
|
150
|
+
/**
|
|
151
|
+
* After the factory failed and the stale value was served, how long that
|
|
152
|
+
* value counts as fresh before the factory is tried again. Default
|
|
153
|
+
* `'10s'` (or the store's); `0` or `null` retries on the next call.
|
|
154
|
+
*/
|
|
155
|
+
graceBackoff?: Duration;
|
|
150
156
|
/** Soft timeout: on a stale hit, return the stale value if the factory is slower, then refresh in the background. */
|
|
151
157
|
timeout?: Duration;
|
|
152
158
|
/** Hard timeout: reject with {@link TimeoutError} if the factory exceeds it (even without a stale fallback). */
|
|
@@ -180,18 +186,40 @@ export interface ExpireOptions {
|
|
|
180
186
|
key: string;
|
|
181
187
|
}
|
|
182
188
|
|
|
183
|
-
/**
|
|
189
|
+
/**
|
|
190
|
+
* Payloads for each emitted cache event (bento event-name parity).
|
|
191
|
+
*
|
|
192
|
+
* Upstream's fields, plus two of our own that a profiler needs and upstream's
|
|
193
|
+
* payloads do not carry: `duration`, the milliseconds from the call to the
|
|
194
|
+
* event, and on a write its `ttl`, as Laravel's `KeyWritten` reports it.
|
|
195
|
+
* Additive: a listener written against upstream's shape reads what it read.
|
|
196
|
+
*/
|
|
184
197
|
export interface CacheEventMap {
|
|
185
198
|
"cache:hit": {
|
|
186
199
|
key: string;
|
|
187
200
|
value: unknown;
|
|
188
201
|
store: string;
|
|
189
202
|
graced: boolean;
|
|
203
|
+
duration: number;
|
|
204
|
+
};
|
|
205
|
+
/**
|
|
206
|
+
* Reported once the call is served. For `getOrSet` that is after its
|
|
207
|
+
* factory ran, as upstream reports it, so `duration` includes the factory.
|
|
208
|
+
*/
|
|
209
|
+
"cache:miss": { key: string; store: string; duration: number };
|
|
210
|
+
"cache:written": {
|
|
211
|
+
key: string;
|
|
212
|
+
value: unknown;
|
|
213
|
+
store: string;
|
|
214
|
+
/** Seconds the entry lives, `null` when it never expires. */
|
|
215
|
+
ttl: number | null;
|
|
216
|
+
/** The write alone: a `getOrSet`'s factory is counted in its miss. */
|
|
217
|
+
duration: number;
|
|
190
218
|
};
|
|
191
|
-
"cache:
|
|
192
|
-
"cache:
|
|
193
|
-
|
|
194
|
-
"cache:
|
|
219
|
+
"cache:deleted": { key: string; store: string; duration: number };
|
|
220
|
+
"cache:cleared": { store: string; duration: number };
|
|
221
|
+
/** A key marked stale by `expire()`, kept for its grace window or dropped. */
|
|
222
|
+
"cache:expire": { key: string; store: string; duration: number };
|
|
195
223
|
}
|
|
196
224
|
|
|
197
225
|
/**
|
|
@@ -86,6 +86,27 @@ export function hasCommands(
|
|
|
86
86
|
return missingCommands(value, commands).length === 0;
|
|
87
87
|
}
|
|
88
88
|
|
|
89
|
+
/**
|
|
90
|
+
* Whether a client resolved earlier has ended for good, and must be resolved
|
|
91
|
+
* again rather than used.
|
|
92
|
+
*
|
|
93
|
+
* ioredis reaches `end` once its retry strategy gives up (quasar's generated
|
|
94
|
+
* config gives up after ten attempts, about three seconds of outage), or after
|
|
95
|
+
* `quit()`/`disconnect()`. From there every command rejects with "Connection is
|
|
96
|
+
* closed." and the client never comes back. Quasar drops such a connection and
|
|
97
|
+
* hands out a fresh one on the next `connection(name)`, so a store that kept
|
|
98
|
+
* the first answer of its resolver stayed on the dead client until the process
|
|
99
|
+
* restarted, even once Redis was back.
|
|
100
|
+
*
|
|
101
|
+
* `close` is NOT terminal: ioredis reconnects from it by itself, and throwing
|
|
102
|
+
* that client away would leak its socket. A client with no `status` (a test
|
|
103
|
+
* double, another library) never counts as ended. Only meaningful for a
|
|
104
|
+
* resolver: a client handed in directly is the caller's to replace.
|
|
105
|
+
*/
|
|
106
|
+
export function hasEnded(client: unknown): boolean {
|
|
107
|
+
return memberValue(readMember(client, "status")) === "end";
|
|
108
|
+
}
|
|
109
|
+
|
|
89
110
|
export interface QuasarConnectionRequest<T> {
|
|
90
111
|
/** The package asking. It prefixes every message this can raise. */
|
|
91
112
|
pkg: string;
|