@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.
@@ -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. Needs `serialize`.
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 ceilings.
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
- * Expired ones go first — evicting a live entry while a dead one sits in
151
- * the map would throw away a value someone still wants. Only if that is not
152
- * enough does it take the least recently used: the Map's order, since a
153
- * read moves its key to the end as a write does.
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 (this.#maxEntrySize > 0 && size > this.#maxEntrySize) {
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
- this.#enforceCeiling();
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
- if (physicalTtlSeconds > 0) {
399
- const currentTtl = await client.ttl(tagKey);
400
- if (currentTtl < 0 || indexTtl > currentTtl) {
401
- await client.expire(tagKey, indexTtl);
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
- ).then((loaded) => {
183
- const source = isConnectionSource(loaded)
184
- ? loaded.connection(options?.connection)
185
- : loaded;
186
- if (!isPubSubSource(source)) {
187
- throw new EchoError(
188
- "E_ECHO_INCOMPLETE_CONNECTION",
189
- "Echo: the quasar connection does not expose publish()/subscribe()",
190
- );
191
- }
192
- return source;
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
- // Waited on through the callbacks, not on the call's return value:
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
- /** Payloads for each emitted cache event (bento event-name parity). */
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:miss": { key: string; store: string };
192
- "cache:written": { key: string; value: unknown; store: string };
193
- "cache:deleted": { key: string; store: string };
194
- "cache:cleared": { store: string };
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;