@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/quasar.ts
CHANGED
|
@@ -12,8 +12,17 @@
|
|
|
12
12
|
*/
|
|
13
13
|
|
|
14
14
|
import type { RedisClient } from "./drivers/RedisDriver.js";
|
|
15
|
-
import
|
|
16
|
-
|
|
15
|
+
import {
|
|
16
|
+
type BusMessage,
|
|
17
|
+
type CacheBus,
|
|
18
|
+
isBusMessage,
|
|
19
|
+
} from "./drivers/TieredDriver.js";
|
|
20
|
+
import { EchoError } from "./errors.js";
|
|
21
|
+
import {
|
|
22
|
+
hasCommands,
|
|
23
|
+
hasEnded,
|
|
24
|
+
quasarConnection as loadQuasarConnection,
|
|
25
|
+
} from "./vendor/quasarConnection.js";
|
|
17
26
|
|
|
18
27
|
/**
|
|
19
28
|
* The commands this driver actually issues.
|
|
@@ -33,21 +42,44 @@ const REQUIRED = [
|
|
|
33
42
|
"srem",
|
|
34
43
|
"smembers",
|
|
35
44
|
"expire",
|
|
45
|
+
"persist",
|
|
36
46
|
"ttl",
|
|
37
47
|
] as const;
|
|
38
48
|
|
|
49
|
+
/**
|
|
50
|
+
* The connection is handed over only once it carries every command above.
|
|
51
|
+
* `keys` and `exists` are declared but never called, so not required either;
|
|
52
|
+
* `scan` stays optional, but when there it has to be a function too.
|
|
53
|
+
*/
|
|
54
|
+
function isRedisClient(value: unknown): value is RedisClient {
|
|
55
|
+
return (
|
|
56
|
+
hasCommands(value, REQUIRED) &&
|
|
57
|
+
(!("scan" in value) ||
|
|
58
|
+
value.scan === undefined ||
|
|
59
|
+
typeof value.scan === "function")
|
|
60
|
+
);
|
|
61
|
+
}
|
|
62
|
+
|
|
39
63
|
/**
|
|
40
64
|
* A resolver for `drivers.redis({ connection })` — quasar is loaded on the
|
|
41
65
|
* first cache command, not at config time.
|
|
42
66
|
*/
|
|
43
67
|
export function quasarConnection(name?: string): () => Promise<RedisClient> {
|
|
44
68
|
return async () =>
|
|
45
|
-
loadQuasarConnection
|
|
69
|
+
loadQuasarConnection({
|
|
46
70
|
pkg: "echo",
|
|
47
71
|
name,
|
|
48
72
|
required: REQUIRED,
|
|
73
|
+
isConnection: isRedisClient,
|
|
49
74
|
what: "the cache store",
|
|
50
|
-
raise: (
|
|
75
|
+
raise: (reason, message, cause) =>
|
|
76
|
+
new EchoError(
|
|
77
|
+
reason === "quasar-missing"
|
|
78
|
+
? "E_ECHO_QUASAR_MISSING"
|
|
79
|
+
: "E_ECHO_INCOMPLETE_CONNECTION",
|
|
80
|
+
message,
|
|
81
|
+
{ cause },
|
|
82
|
+
),
|
|
51
83
|
});
|
|
52
84
|
}
|
|
53
85
|
|
|
@@ -114,7 +146,8 @@ async function loadQuasar(context: string): Promise<unknown> {
|
|
|
114
146
|
? loaded
|
|
115
147
|
: Reflect.get(Object(loaded), "default");
|
|
116
148
|
} catch (cause) {
|
|
117
|
-
throw new
|
|
149
|
+
throw new EchoError(
|
|
150
|
+
"E_ECHO_QUASAR_MISSING",
|
|
118
151
|
`Echo: ${context}, but @c9up/quasar is not installed.\n pnpm add @c9up/quasar`,
|
|
119
152
|
{ cause },
|
|
120
153
|
);
|
|
@@ -145,20 +178,109 @@ export function quasarBus(options?: {
|
|
|
145
178
|
Promise<(raw: string) => void>
|
|
146
179
|
>();
|
|
147
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
|
+
|
|
148
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
|
+
}
|
|
149
251
|
ready ??= loadQuasar(
|
|
150
252
|
`the cache bus asks for the "${options?.connection ?? "default"}" quasar connection`,
|
|
151
|
-
)
|
|
152
|
-
|
|
153
|
-
|
|
154
|
-
|
|
155
|
-
|
|
156
|
-
|
|
157
|
-
|
|
158
|
-
|
|
159
|
-
|
|
160
|
-
|
|
161
|
-
|
|
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
|
+
});
|
|
162
284
|
return ready;
|
|
163
285
|
};
|
|
164
286
|
|
|
@@ -169,11 +291,15 @@ export function quasarBus(options?: {
|
|
|
169
291
|
},
|
|
170
292
|
async subscribe(handler: (message: BusMessage) => void): Promise<void> {
|
|
171
293
|
const wrapper = (raw: string): void => {
|
|
294
|
+
let frame: unknown;
|
|
172
295
|
try {
|
|
173
|
-
|
|
296
|
+
frame = JSON.parse(raw);
|
|
174
297
|
} catch {
|
|
175
|
-
|
|
298
|
+
// A malformed frame is not a reason to stop listening.
|
|
299
|
+
return;
|
|
176
300
|
}
|
|
301
|
+
// Anything on the channel reaches here, not only what echo sent.
|
|
302
|
+
if (isBusMessage(frame)) handler(frame);
|
|
177
303
|
};
|
|
178
304
|
// AWAITED, and a reported failure becomes a rejection.
|
|
179
305
|
//
|
|
@@ -188,18 +314,7 @@ export function quasarBus(options?: {
|
|
|
188
314
|
// quietly incoherent.
|
|
189
315
|
const attempt = (async (): Promise<(raw: string) => void> => {
|
|
190
316
|
const source = await manager();
|
|
191
|
-
|
|
192
|
-
// `subscribe` reports a failure rather than rejecting, and newer
|
|
193
|
-
// quasar declares it `void`. This shape is correct against both.
|
|
194
|
-
await new Promise<void>((resolve, reject) => {
|
|
195
|
-
source.subscribe(channel, wrapper, {
|
|
196
|
-
onSubscription: () => resolve(),
|
|
197
|
-
onError: (error) => {
|
|
198
|
-
opened.delete(handler);
|
|
199
|
-
reject(error instanceof Error ? error : new Error(String(error)));
|
|
200
|
-
},
|
|
201
|
-
});
|
|
202
|
-
});
|
|
317
|
+
await listen(source, wrapper);
|
|
203
318
|
return wrapper;
|
|
204
319
|
})();
|
|
205
320
|
opened.set(handler, attempt);
|
package/src/services/main.ts
CHANGED
|
@@ -11,7 +11,8 @@
|
|
|
11
11
|
* const cached = await cache.get<User>('user:42')
|
|
12
12
|
*/
|
|
13
13
|
|
|
14
|
-
import
|
|
14
|
+
import { CacheManager } from "../CacheManager.js";
|
|
15
|
+
import { EchoError } from "../errors.js";
|
|
15
16
|
|
|
16
17
|
let instance: CacheManager | undefined;
|
|
17
18
|
|
|
@@ -33,7 +34,29 @@ export function clearCache(): void {
|
|
|
33
34
|
instance = undefined;
|
|
34
35
|
}
|
|
35
36
|
|
|
36
|
-
|
|
37
|
+
/**
|
|
38
|
+
* What the proxy stands on. Never reached: every read goes through the trap
|
|
39
|
+
* below, to the bound manager or to the not-booted error. A real instance
|
|
40
|
+
* rather than an asserted `{}`, so the proxy is a `CacheManager` by type.
|
|
41
|
+
*/
|
|
42
|
+
const unbooted = (): Promise<never> => Promise.reject(notBooted());
|
|
43
|
+
const placeholder = new CacheManager({
|
|
44
|
+
get: unbooted,
|
|
45
|
+
set: unbooted,
|
|
46
|
+
delete: unbooted,
|
|
47
|
+
flush: unbooted,
|
|
48
|
+
has: unbooted,
|
|
49
|
+
});
|
|
50
|
+
|
|
51
|
+
function notBooted(): EchoError {
|
|
52
|
+
return new EchoError(
|
|
53
|
+
"E_ECHO_NOT_BOOTED",
|
|
54
|
+
"[echo] CacheManager singleton accessed before EchoProvider.boot() ran " +
|
|
55
|
+
"or `setCache(myCache)` was called. Wire one of them first.",
|
|
56
|
+
);
|
|
57
|
+
}
|
|
58
|
+
|
|
59
|
+
const cache: CacheManager = new Proxy(placeholder, {
|
|
37
60
|
get(_target, prop) {
|
|
38
61
|
// A module loader inspects what it imports before anyone uses it: it reads
|
|
39
62
|
// `then` to decide whether the namespace is thenable, and various symbols
|
|
@@ -44,12 +67,7 @@ const cache: CacheManager = new Proxy({} as CacheManager, {
|
|
|
44
67
|
if (typeof prop === "symbol" || prop === "then") {
|
|
45
68
|
return undefined;
|
|
46
69
|
}
|
|
47
|
-
if (!instance)
|
|
48
|
-
throw new Error(
|
|
49
|
-
"[echo] CacheManager singleton accessed before EchoProvider.boot() ran " +
|
|
50
|
-
"or `setCache(myCache)` was called. Wire one of them first.",
|
|
51
|
-
);
|
|
52
|
-
}
|
|
70
|
+
if (!instance) throw notBooted();
|
|
53
71
|
const value = Reflect.get(instance, prop, instance);
|
|
54
72
|
return typeof value === "function" ? value.bind(instance) : value;
|
|
55
73
|
},
|
package/src/types.ts
CHANGED
|
@@ -4,7 +4,7 @@
|
|
|
4
4
|
*/
|
|
5
5
|
|
|
6
6
|
import type { Duration } from "./duration.js";
|
|
7
|
-
import type { FactoryError } from "./errors.js";
|
|
7
|
+
import type { FactoryError, LockTimeoutError } from "./errors.js";
|
|
8
8
|
|
|
9
9
|
/**
|
|
10
10
|
* A driver-level entry. `stale` is `true` when the value is past its logical
|
|
@@ -20,6 +20,13 @@ export interface CacheEntry<T = unknown> {
|
|
|
20
20
|
* promotes an entry between tiers instead of resetting it to immortal.
|
|
21
21
|
*/
|
|
22
22
|
expiresAt?: number;
|
|
23
|
+
/**
|
|
24
|
+
* The tags the entry was written with, when the driver keeps them. A
|
|
25
|
+
* composing driver needs them to promote an entry between tiers: a
|
|
26
|
+
* promoted copy written without its tags was invisible to `deleteByTag`
|
|
27
|
+
* on the very instance that promoted it.
|
|
28
|
+
*/
|
|
29
|
+
tags?: string[];
|
|
23
30
|
}
|
|
24
31
|
|
|
25
32
|
/** Options for the grace-aware {@link CacheDriver.setEntry}. */
|
|
@@ -140,11 +147,21 @@ export interface GetOrSetOptions<T> {
|
|
|
140
147
|
factory: Factory<T>;
|
|
141
148
|
ttl?: Duration;
|
|
142
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;
|
|
143
156
|
/** Soft timeout: on a stale hit, return the stale value if the factory is slower, then refresh in the background. */
|
|
144
157
|
timeout?: Duration;
|
|
145
158
|
/** Hard timeout: reject with {@link TimeoutError} if the factory exceeds it (even without a stale fallback). */
|
|
146
159
|
hardTimeout?: Duration;
|
|
147
|
-
/**
|
|
160
|
+
/**
|
|
161
|
+
* Max time to wait on another caller's in-flight factory for the same key
|
|
162
|
+
* (single-flight lock). Past it the stale value is returned when there is
|
|
163
|
+
* one, and a {@link LockTimeoutError} is thrown when there is not.
|
|
164
|
+
*/
|
|
148
165
|
lockTimeout?: Duration;
|
|
149
166
|
tags?: string[];
|
|
150
167
|
/** Observe factory failures (foreground and background). */
|
|
@@ -169,18 +186,40 @@ export interface ExpireOptions {
|
|
|
169
186
|
key: string;
|
|
170
187
|
}
|
|
171
188
|
|
|
172
|
-
/**
|
|
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
|
+
*/
|
|
173
197
|
export interface CacheEventMap {
|
|
174
198
|
"cache:hit": {
|
|
175
199
|
key: string;
|
|
176
200
|
value: unknown;
|
|
177
201
|
store: string;
|
|
178
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;
|
|
179
218
|
};
|
|
180
|
-
"cache:
|
|
181
|
-
"cache:
|
|
182
|
-
|
|
183
|
-
"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 };
|
|
184
223
|
}
|
|
185
224
|
|
|
186
225
|
/**
|
|
@@ -31,23 +31,83 @@ interface ConnectionSource {
|
|
|
31
31
|
* `"connection" in manager` is FALSE while reading it returns the function —
|
|
32
32
|
* gating on `in` rejected the real manager. And a module namespace under a
|
|
33
33
|
* test double RAISES for an export it does not have, rather than answering
|
|
34
|
-
* undefined, so a bare read fails on the mock.
|
|
35
|
-
*
|
|
34
|
+
* undefined, so a bare read fails on the mock.
|
|
35
|
+
*
|
|
36
|
+
* So the read is caught, but what it raised is kept: on quasar's accessor a
|
|
37
|
+
* throw is not an absence, it is the accessor saying its provider has not
|
|
38
|
+
* booted, and dropping that turned it into a wrong diagnosis.
|
|
36
39
|
*/
|
|
37
|
-
|
|
38
|
-
|
|
40
|
+
type MemberRead = { value: unknown } | { threw: unknown };
|
|
41
|
+
|
|
42
|
+
function readMember(value: unknown, name: string): MemberRead {
|
|
43
|
+
if (typeof value !== "object" || value === null) return { value: undefined };
|
|
39
44
|
try {
|
|
40
|
-
return Reflect.get(value, name);
|
|
41
|
-
} catch {
|
|
42
|
-
return
|
|
45
|
+
return { value: Reflect.get(value, name) };
|
|
46
|
+
} catch (threw) {
|
|
47
|
+
return { threw };
|
|
43
48
|
}
|
|
44
49
|
}
|
|
45
50
|
|
|
51
|
+
function memberValue(read: MemberRead): unknown {
|
|
52
|
+
return "value" in read ? read.value : undefined;
|
|
53
|
+
}
|
|
54
|
+
|
|
46
55
|
function isConnectionSource(value: unknown): value is ConnectionSource {
|
|
47
|
-
return typeof readMember(value, "connection") === "function";
|
|
56
|
+
return typeof memberValue(readMember(value, "connection")) === "function";
|
|
48
57
|
}
|
|
49
58
|
|
|
50
|
-
|
|
59
|
+
/**
|
|
60
|
+
* The commands among `commands` that `value` does not carry as functions.
|
|
61
|
+
*
|
|
62
|
+
* Reads go through the same catch as above, so a command whose read throws
|
|
63
|
+
* counts as missing.
|
|
64
|
+
*/
|
|
65
|
+
export function missingCommands(
|
|
66
|
+
value: unknown,
|
|
67
|
+
commands: readonly string[],
|
|
68
|
+
): string[] {
|
|
69
|
+
return commands.filter(
|
|
70
|
+
(command) => typeof memberValue(readMember(value, command)) !== "function",
|
|
71
|
+
);
|
|
72
|
+
}
|
|
73
|
+
|
|
74
|
+
/**
|
|
75
|
+
* Whether `value` carries every one of `commands` as a function.
|
|
76
|
+
*
|
|
77
|
+
* The building block of the guard a caller passes as `isConnection`, over the
|
|
78
|
+
* same list it passes as `required` — which is what names the gap when the
|
|
79
|
+
* guard says no.
|
|
80
|
+
*/
|
|
81
|
+
export function hasCommands(
|
|
82
|
+
value: unknown,
|
|
83
|
+
commands: readonly string[],
|
|
84
|
+
): value is object {
|
|
85
|
+
if (typeof value !== "object" || value === null) return false;
|
|
86
|
+
return missingCommands(value, commands).length === 0;
|
|
87
|
+
}
|
|
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
|
+
|
|
110
|
+
export interface QuasarConnectionRequest<T> {
|
|
51
111
|
/** The package asking. It prefixes every message this can raise. */
|
|
52
112
|
pkg: string;
|
|
53
113
|
/**
|
|
@@ -65,8 +125,16 @@ export interface QuasarConnectionRequest {
|
|
|
65
125
|
) => Error;
|
|
66
126
|
/** Connection name, or `undefined` for quasar's default. */
|
|
67
127
|
name?: string;
|
|
68
|
-
/** The commands the caller will actually issue. */
|
|
128
|
+
/** The commands the caller will actually issue, named in the message. */
|
|
69
129
|
required: readonly string[];
|
|
130
|
+
/**
|
|
131
|
+
* The caller's check that the connection is the client it needs.
|
|
132
|
+
*
|
|
133
|
+
* Written by the caller over the commands it issues (`hasCommands` with
|
|
134
|
+
* `required` does it), because only the caller knows its client type. The
|
|
135
|
+
* connection is handed over only once this has said yes.
|
|
136
|
+
*/
|
|
137
|
+
isConnection: (value: unknown) => value is T;
|
|
70
138
|
/** What the caller does with them, for the message that names a gap. */
|
|
71
139
|
what: string;
|
|
72
140
|
/**
|
|
@@ -86,9 +154,10 @@ export interface QuasarConnectionRequest {
|
|
|
86
154
|
* command, far from the line that asked for it.
|
|
87
155
|
*/
|
|
88
156
|
export async function quasarConnection<T>(
|
|
89
|
-
request: QuasarConnectionRequest
|
|
157
|
+
request: QuasarConnectionRequest<T>,
|
|
90
158
|
): Promise<T> {
|
|
91
|
-
const { pkg, name, required, what, raise, alternative } =
|
|
159
|
+
const { pkg, name, required, what, raise, alternative, isConnection } =
|
|
160
|
+
request;
|
|
92
161
|
const specifier = "@c9up/quasar/services/main";
|
|
93
162
|
let loaded: unknown;
|
|
94
163
|
try {
|
|
@@ -102,9 +171,22 @@ export async function quasarConnection<T>(
|
|
|
102
171
|
);
|
|
103
172
|
}
|
|
104
173
|
|
|
105
|
-
|
|
106
|
-
|
|
107
|
-
|
|
174
|
+
// The namespace itself may be the manager (a test double); a throw there is
|
|
175
|
+
// the mock refusing an export it lacks, not an answer.
|
|
176
|
+
const direct = memberValue(readMember(loaded, "connection"));
|
|
177
|
+
const manager =
|
|
178
|
+
typeof direct === "function"
|
|
179
|
+
? loaded
|
|
180
|
+
: memberValue(readMember(Object(loaded), "default"));
|
|
181
|
+
const read = readMember(manager, "connection");
|
|
182
|
+
if ("threw" in read) {
|
|
183
|
+
throw raise(
|
|
184
|
+
"quasar-missing",
|
|
185
|
+
`[${pkg}] ${what} asks for the quasar connection "${name ?? "default"}", but @c9up/quasar's manager is not available yet: ` +
|
|
186
|
+
"its provider has not booted, or is not registered in this application's providers.",
|
|
187
|
+
read.threw,
|
|
188
|
+
);
|
|
189
|
+
}
|
|
108
190
|
if (!isConnectionSource(manager)) {
|
|
109
191
|
throw raise(
|
|
110
192
|
"quasar-missing",
|
|
@@ -113,17 +195,18 @@ export async function quasarConnection<T>(
|
|
|
113
195
|
}
|
|
114
196
|
|
|
115
197
|
const connection = manager.connection(name);
|
|
116
|
-
const missing = required
|
|
117
|
-
(command) => typeof readMember(connection, command) !== "function",
|
|
118
|
-
);
|
|
198
|
+
const missing = missingCommands(connection, required);
|
|
119
199
|
if (missing.length > 0) {
|
|
120
200
|
throw raise(
|
|
121
201
|
"incomplete-connection",
|
|
122
202
|
`[${pkg}] the quasar connection${name ? ` '${name}'` : ""} is missing ${missing.join(", ")}, which ${what} issues`,
|
|
123
203
|
);
|
|
124
204
|
}
|
|
125
|
-
|
|
126
|
-
|
|
127
|
-
|
|
128
|
-
|
|
205
|
+
if (!isConnection(connection)) {
|
|
206
|
+
throw raise(
|
|
207
|
+
"incomplete-connection",
|
|
208
|
+
`[${pkg}] the quasar connection${name ? ` '${name}'` : ""} is not the client ${what} needs`,
|
|
209
|
+
);
|
|
210
|
+
}
|
|
211
|
+
return connection;
|
|
129
212
|
}
|