@bymax-one/nest-realtime 1.2.17 → 1.2.19

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.
@@ -1,5 +1,5 @@
1
1
  import { randomUUID } from 'crypto';
2
- import { Injectable, Optional, Inject, Logger, Global, Module, ServiceUnavailableException, UseGuards, Sse, Req, Res, Controller, InternalServerErrorException, HttpException, UnauthorizedException } from '@nestjs/common';
2
+ import { Injectable, Optional, Inject, Logger, Global, Module, ServiceUnavailableException, UseGuards, Sse, Req, Res, Controller, InternalServerErrorException, HttpException, HttpStatus, UnauthorizedException } from '@nestjs/common';
3
3
  import { Subject, of, EMPTY, Observable, merge } from 'rxjs';
4
4
  import { takeUntil, catchError, finalize } from 'rxjs/operators';
5
5
  import { isIP } from 'net';
@@ -41,6 +41,85 @@ var REALTIME_ERROR_CODES = {
41
41
  REPLAY_BUFFER_MISS: "REALTIME_REPLAY_BUFFER_MISS"
42
42
  };
43
43
 
44
+ // src/server/utils/is-plain-object.ts
45
+ function isPlainObject(value) {
46
+ if (typeof value !== "object") return false;
47
+ try {
48
+ return Object.prototype.toString.call(value) === "[object Object]";
49
+ } catch {
50
+ return false;
51
+ }
52
+ }
53
+
54
+ // src/server/config/drop-unset.ts
55
+ var SSE_KEYS = {
56
+ endpoint: true,
57
+ heartbeatMs: true,
58
+ replayBufferSize: true,
59
+ replayTtlMs: true,
60
+ replayMaxIdleUsers: true,
61
+ maxConnectionsPerUser: true,
62
+ emitConnectionEvent: true,
63
+ maxQueuedBytes: true,
64
+ maxQueuedEvents: true,
65
+ stallHeartbeats: true
66
+ };
67
+ var WEBSOCKET_KEYS = {
68
+ namespace: true,
69
+ cors: true,
70
+ maxHttpBufferSize: true,
71
+ pingIntervalMs: true,
72
+ pingTimeoutMs: true,
73
+ maxConnectionsPerUser: true,
74
+ emitConnectionEvent: true,
75
+ redisAdapter: true
76
+ };
77
+ var REAUTHENTICATION_KEYS = {
78
+ intervalSeconds: true,
79
+ onFailure: true,
80
+ cacheTtlMs: true,
81
+ revalidateTimeoutMs: true,
82
+ concurrency: true
83
+ };
84
+ var TOP_LEVEL_KEYS = {
85
+ transport: true,
86
+ authenticator: true,
87
+ tenantResolver: true,
88
+ hooks: true,
89
+ hookTimeoutMs: true,
90
+ onConnectFailure: true,
91
+ authenticateTimeoutMs: true,
92
+ maxPendingHandshakes: true,
93
+ maxConnections: true,
94
+ pubsub: true,
95
+ offlineQueue: true,
96
+ presence: true,
97
+ sse: true,
98
+ websocket: true,
99
+ reauthenticationPolicy: true
100
+ };
101
+ var GROUPS = {
102
+ sse: SSE_KEYS,
103
+ websocket: WEBSOCKET_KEYS,
104
+ reauthenticationPolicy: REAUTHENTICATION_KEYS
105
+ };
106
+ function readSet(source, known) {
107
+ const kept = {};
108
+ for (const key of /* @__PURE__ */ new Set([...Object.keys(source), ...Object.keys(known)])) {
109
+ const value = source[key];
110
+ if (value !== void 0 && value !== null) kept[key] = value;
111
+ }
112
+ return kept;
113
+ }
114
+ function dropUnset(options) {
115
+ const kept = readSet(options, TOP_LEVEL_KEYS);
116
+ for (const [group, keys] of Object.entries(GROUPS)) {
117
+ const value = kept[group];
118
+ if (isPlainObject(value)) kept[group] = readSet(value, keys);
119
+ }
120
+ return kept;
121
+ }
122
+
44
123
  // src/server/config/default-options.ts
45
124
  var DEFAULT_SSE = {
46
125
  endpoint: "/realtime/sse",
@@ -54,7 +133,8 @@ var DEFAULT_SSE = {
54
133
  maxQueuedEvents: 1e3,
55
134
  stallHeartbeats: 3
56
135
  };
57
- function applyDefaults(options) {
136
+ function applyDefaults(raw) {
137
+ const options = dropUnset(raw);
58
138
  return Object.freeze({
59
139
  ...options,
60
140
  sse: { ...DEFAULT_SSE, ...options.sse ?? {} }
@@ -75,6 +155,25 @@ var DEFAULT_HOOK_TIMEOUT_MS = 5e3;
75
155
  var HEARTBEAT_MIN_MS = 5e3;
76
156
  var HEARTBEAT_MAX_MS = 9e4;
77
157
 
158
+ // src/server/utils/describe-received.ts
159
+ var KIND_OF_TYPE = {
160
+ string: "a string",
161
+ boolean: "a boolean",
162
+ bigint: "a bigint",
163
+ symbol: "a symbol",
164
+ function: "a function",
165
+ undefined: "undefined"
166
+ };
167
+ function describeReceived(value) {
168
+ if (typeof value === "number") {
169
+ return Number.isFinite(value) ? String(value) : "a number that is not finite";
170
+ }
171
+ if (value === null) return "null";
172
+ if (Array.isArray(value)) return "an array";
173
+ if (typeof value === "object" && !isPlainObject(value)) return "a built-in object";
174
+ return KIND_OF_TYPE[typeof value] ?? "an object";
175
+ }
176
+
78
177
  // src/server/utils/realtime-error.ts
79
178
  function realtimeError(code, detail, options = {}) {
80
179
  const lead = options.who === void 0 ? code : `[${options.who}] ${code}`;
@@ -83,13 +182,93 @@ function realtimeError(code, detail, options = {}) {
83
182
  return Object.assign(error, { code });
84
183
  }
85
184
 
185
+ // src/server/utils/refuse-object.ts
186
+ function refuseObject(who, path, value) {
187
+ throw realtimeError(
188
+ REALTIME_ERROR_CODES.INVALID_OPTIONS,
189
+ `${path} must be an object, received ${describeReceived(value)}`,
190
+ { who }
191
+ );
192
+ }
193
+
194
+ // src/server/config/validate-shapes.ts
195
+ var REQUIRED_FUNCTIONS = {
196
+ pubsub: ["publish", "subscribe"],
197
+ offlineQueue: ["append", "retrieveSince", "acknowledge"],
198
+ presence: ["setOnline", "setOffline", "isOnline", "listOnlineByTenant", "countOnline"]
199
+ };
200
+ var HOOK_NAMES = [
201
+ "onConnect",
202
+ "onDisconnect",
203
+ "onError",
204
+ "onReauthenticationFailed",
205
+ "onDeliveryFailure"
206
+ ];
207
+ var GROUP_NAMES = ["sse", "websocket", "reauthenticationPolicy"];
208
+ function refuse(path, expected, received) {
209
+ throw realtimeError(
210
+ REALTIME_ERROR_CODES.INVALID_OPTIONS,
211
+ `options.${path} must be ${expected}, received ${describeReceived(received)}`,
212
+ { who: "BymaxRealtimeModule" }
213
+ );
214
+ }
215
+ function assertObject(path, value) {
216
+ if (value !== void 0 && !isPlainObject(value)) refuse(path, "an object", value);
217
+ }
218
+ function assertFunction(path, value) {
219
+ if (typeof value !== "function") refuse(path, "a function", value);
220
+ }
221
+ function assertOptionalFunction(path, value) {
222
+ if (value !== void 0 && value !== null) assertFunction(path, value);
223
+ }
224
+ function assertBoolean(path, value) {
225
+ if (value !== void 0 && typeof value !== "boolean") refuse(path, "a boolean", value);
226
+ }
227
+ function assertSseEndpoint(path, value) {
228
+ if (value === void 0 || value === null) return;
229
+ if (typeof value !== "string" || value.trim().length === 0) {
230
+ refuse(path, "a non-blank string", value);
231
+ }
232
+ if (/\s/.test(value)) refuse(path, "a string without whitespace", value);
233
+ }
234
+ function assertOptionsObject(value, who = "BymaxRealtimeModule") {
235
+ if (!isPlainObject(value)) refuseObject(who, "options", value);
236
+ }
237
+ function validatePieces(options) {
238
+ for (const [name, functions] of Object.entries(REQUIRED_FUNCTIONS)) {
239
+ const piece = options[name];
240
+ assertObject(name, piece);
241
+ if (piece === void 0) continue;
242
+ for (const fn of functions)
243
+ assertFunction(`${name}.${fn}`, piece[fn]);
244
+ }
245
+ }
246
+ function validateHooks(options) {
247
+ const hooks = options.hooks;
248
+ assertObject("hooks", hooks);
249
+ if (hooks === void 0) return;
250
+ for (const hook of HOOK_NAMES)
251
+ assertOptionalFunction(`hooks.${hook}`, hooks[hook]);
252
+ }
253
+ function validateShapes(options) {
254
+ for (const group of GROUP_NAMES) assertObject(group, options[group]);
255
+ validatePieces(options);
256
+ validateHooks(options);
257
+ assertOptionalFunction("tenantResolver", options.tenantResolver);
258
+ assertBoolean("sse.emitConnectionEvent", options.sse?.emitConnectionEvent);
259
+ assertBoolean("websocket.emitConnectionEvent", options.websocket?.emitConnectionEvent);
260
+ assertSseEndpoint("sse.endpoint", options.sse?.endpoint);
261
+ }
262
+
86
263
  // src/server/config/validate-options.ts
87
264
  var VALID_TRANSPORTS = /* @__PURE__ */ new Set(["sse", "websocket", "both"]);
88
- function validateOptions(options) {
265
+ function validateOptions(raw) {
266
+ assertOptionsObject(raw);
267
+ const options = dropUnset(raw);
89
268
  if (!options.transport || !VALID_TRANSPORTS.has(options.transport)) {
90
269
  throw realtimeError(
91
270
  REALTIME_ERROR_CODES.INVALID_OPTIONS,
92
- `options.transport must be one of 'sse' | 'websocket' | 'both' (got: ${String(options.transport)})`,
271
+ `options.transport must be one of 'sse' | 'websocket' | 'both', received ${describeReceived(options.transport)}`,
93
272
  { who: "BymaxRealtimeModule" }
94
273
  );
95
274
  }
@@ -107,6 +286,7 @@ function validateOptions(options) {
107
286
  { who: "BymaxRealtimeModule" }
108
287
  );
109
288
  }
289
+ validateShapes(options);
110
290
  validateHookTimeout(options);
111
291
  validateOnConnectFailure(options);
112
292
  validateSseOptions(options);
@@ -122,7 +302,7 @@ function assertInteger(path, value, least, most) {
122
302
  if (valid) return;
123
303
  throw realtimeError(
124
304
  REALTIME_ERROR_CODES.INVALID_OPTIONS,
125
- `options.${path} must be an integer >= ${least}${most === void 0 ? "" : ` and <= ${most}`}, got ${String(value)}${most === void 0 && Number.isInteger(value) && !Number.isSafeInteger(value) ? ` (the most is ${Number.MAX_SAFE_INTEGER})` : ""}`,
305
+ `options.${path} must be an integer >= ${least}${most === void 0 ? "" : ` and <= ${most}`}, received ${describeReceived(value)}${most === void 0 && Number.isInteger(value) && !Number.isSafeInteger(value) ? ` (the most is ${Number.MAX_SAFE_INTEGER})` : ""}`,
126
306
  { who: "BymaxRealtimeModule" }
127
307
  );
128
308
  }
@@ -131,7 +311,7 @@ function validateOnConnectFailure(options) {
131
311
  if (value === void 0 || value === "ignore" || value === "close") return;
132
312
  throw realtimeError(
133
313
  REALTIME_ERROR_CODES.INVALID_OPTIONS,
134
- `options.onConnectFailure must be 'ignore' or 'close', got ${String(value)}`,
314
+ `options.onConnectFailure must be 'ignore' or 'close', received ${describeReceived(value)}`,
135
315
  { who: "BymaxRealtimeModule" }
136
316
  );
137
317
  }
@@ -170,16 +350,10 @@ function validateReauthPolicy(options) {
170
350
  if (onFailure !== void 0 && onFailure !== "disconnect" && onFailure !== "event") {
171
351
  throw realtimeError(
172
352
  REALTIME_ERROR_CODES.INVALID_OPTIONS,
173
- `options.reauthenticationPolicy.onFailure must be 'disconnect' or 'event', got ${String(onFailure)}`,
353
+ `options.reauthenticationPolicy.onFailure must be 'disconnect' or 'event', received ${describeReceived(onFailure)}`,
174
354
  { who: "BymaxRealtimeModule" }
175
355
  );
176
356
  }
177
- if (policy?.cacheTtlMs !== void 0 && policy.intervalSeconds !== void 0 && policy.cacheTtlMs > policy.intervalSeconds * 1e3) {
178
- Logger.warn(
179
- `[BymaxRealtimeModule] reauthenticationPolicy.cacheTtlMs (${policy.cacheTtlMs} ms) exceeds intervalSeconds*1000 (${policy.intervalSeconds * 1e3} ms): the positive reauth cache outlives the interval, so revalidate is skipped on ticks within the cache window \u2014 reauthentication is effectively weakened`,
180
- "BymaxRealtimeModule"
181
- );
182
- }
183
357
  }
184
358
  function validateSseOptions(options) {
185
359
  const sse = options.sse;
@@ -187,7 +361,7 @@ function validateSseOptions(options) {
187
361
  if (heartbeatMs !== void 0 && !(typeof heartbeatMs === "number" && heartbeatMs >= HEARTBEAT_MIN_MS && heartbeatMs <= HEARTBEAT_MAX_MS)) {
188
362
  throw realtimeError(
189
363
  REALTIME_ERROR_CODES.INVALID_OPTIONS,
190
- `options.sse.heartbeatMs must be between ${HEARTBEAT_MIN_MS} and ${HEARTBEAT_MAX_MS} ms (got ${String(heartbeatMs)})`,
364
+ `options.sse.heartbeatMs must be between ${HEARTBEAT_MIN_MS} and ${HEARTBEAT_MAX_MS} ms, received ${describeReceived(heartbeatMs)}`,
191
365
  { who: "BymaxRealtimeModule" }
192
366
  );
193
367
  }
@@ -199,7 +373,7 @@ function validateSseOptions(options) {
199
373
  if (value !== void 0 && !(typeof value === "number" && Number.isSafeInteger(value) && value >= 0)) {
200
374
  throw realtimeError(
201
375
  REALTIME_ERROR_CODES.INVALID_OPTIONS,
202
- `options.sse.${name} must be an integer >= 0 (0 switches the bound off), got ${String(value)}`,
376
+ `options.sse.${name} must be an integer >= 0 (0 switches the bound off), received ${describeReceived(value)}`,
203
377
  { who: "BymaxRealtimeModule" }
204
378
  );
205
379
  }
@@ -211,6 +385,138 @@ function validateSseOptions(options) {
211
385
  MAX_PER_USER_CONNECTIONS
212
386
  );
213
387
  }
388
+ var REFUSAL_REASONS = ["limit", "unauthorized", "unavailable", "error"];
389
+ var EVICTION_REASONS = ["per_user_cap", "slow_consumer", "revoked"];
390
+ var TALLY_TRANSPORTS = ["sse", "websocket"];
391
+ function zeroed(keys) {
392
+ return Object.fromEntries(keys.map((key) => [key, 0]));
393
+ }
394
+ var _refused, _evicted, _emitted, _slowConsumerDrops;
395
+ var RealtimeMetricsTally = class {
396
+ constructor() {
397
+ __privateAdd(this, _refused, zeroed(REFUSAL_REASONS));
398
+ __privateAdd(this, _evicted, zeroed(EVICTION_REASONS));
399
+ __privateAdd(this, _emitted, zeroed(TALLY_TRANSPORTS));
400
+ __privateAdd(this, _slowConsumerDrops, 0);
401
+ }
402
+ refused(reason) {
403
+ __privateGet(this, _refused)[reason] += 1;
404
+ }
405
+ evicted(reason) {
406
+ __privateGet(this, _evicted)[reason] += 1;
407
+ }
408
+ emitted(transport) {
409
+ __privateGet(this, _emitted)[transport] += 1;
410
+ }
411
+ slowConsumerDropped() {
412
+ __privateSet(this, _slowConsumerDrops, __privateGet(this, _slowConsumerDrops) + 1);
413
+ }
414
+ snapshot() {
415
+ return {
416
+ refused: { ...__privateGet(this, _refused) },
417
+ evicted: { ...__privateGet(this, _evicted) },
418
+ emitted: { ...__privateGet(this, _emitted) },
419
+ slowConsumerDrops: __privateGet(this, _slowConsumerDrops)
420
+ };
421
+ }
422
+ };
423
+ _refused = new WeakMap();
424
+ _evicted = new WeakMap();
425
+ _emitted = new WeakMap();
426
+ _slowConsumerDrops = new WeakMap();
427
+ RealtimeMetricsTally = __decorateClass([
428
+ Injectable()
429
+ ], RealtimeMetricsTally);
430
+ var STATUS_ERROR = 2;
431
+ var TRACER_NAME = "@bymax-one/nest-realtime";
432
+ var LIBRARY_CODE = /^REALTIME_[A-Z_]+$/;
433
+ function codeOf(error) {
434
+ if (typeof error !== "object" || error === null) return "REALTIME_ERROR";
435
+ const { code, message, data } = error;
436
+ for (const candidate of [code, data?.code, message]) {
437
+ if (typeof candidate === "string" && LIBRARY_CODE.test(candidate)) return candidate;
438
+ }
439
+ return "REALTIME_ERROR";
440
+ }
441
+ var _api;
442
+ var RealtimeTracing = class {
443
+ constructor() {
444
+ __privateAdd(this, _api);
445
+ }
446
+ async onModuleInit() {
447
+ try {
448
+ __privateSet(this, _api, await import('@opentelemetry/api'));
449
+ } catch {
450
+ }
451
+ }
452
+ async traced(span, run) {
453
+ let result;
454
+ try {
455
+ result = await run();
456
+ } catch (error) {
457
+ attempt(() => span.setStatus({ code: STATUS_ERROR, message: codeOf(error) }));
458
+ attempt(() => span.end());
459
+ throw error;
460
+ }
461
+ attempt(() => span.end());
462
+ return result;
463
+ }
464
+ span(name, attributes, run) {
465
+ const api = __privateGet(this, _api);
466
+ if (!api) return run();
467
+ const latch = { claimed: false };
468
+ attempt(
469
+ () => api.trace.getTracer(TRACER_NAME).startActiveSpan(name, { attributes }, (span) => {
470
+ if (!latch.claimed) {
471
+ latch.claimed = true;
472
+ latch.started = this.traced(span, run);
473
+ }
474
+ return latch.started;
475
+ })
476
+ );
477
+ if (latch.started) return latch.started;
478
+ latch.claimed = true;
479
+ return run();
480
+ }
481
+ };
482
+ _api = new WeakMap();
483
+ RealtimeTracing = __decorateClass([
484
+ Injectable()
485
+ ], RealtimeTracing);
486
+ function attempt(call) {
487
+ try {
488
+ Promise.resolve(call()).catch(() => void 0);
489
+ } catch {
490
+ }
491
+ }
492
+
493
+ // src/server/utils/log-event.ts
494
+ var REALTIME_LOG_EVENTS = [
495
+ "REALTIME_REAUTH_CACHE_WEAKENS_POLICY",
496
+ "REALTIME_HANDSHAKE_FAILED",
497
+ "REALTIME_HOOK_FAILED",
498
+ "REALTIME_DELIVERY_FAILED",
499
+ "REALTIME_SLOW_CONSUMER",
500
+ "REALTIME_DISCONNECT_FAILED",
501
+ "REALTIME_RECONNECTS_GIVEN_UP",
502
+ "REALTIME_OFFLINE_QUEUE_LIMIT",
503
+ "REALTIME_OFFLINE_QUEUE_ACK_FAILED",
504
+ "REALTIME_PUBSUB_NOT_PROVIDED",
505
+ "REALTIME_PUBSUB_UNSUBSCRIBE_FAILED",
506
+ "REALTIME_PUBSUB_DROPPED",
507
+ "REALTIME_PUBSUB_UNAVAILABLE",
508
+ "REALTIME_CONNECTIONS_REFUSED",
509
+ "REALTIME_HANDSHAKES_REFUSED",
510
+ "REALTIME_REAUTH_FAILED",
511
+ "REALTIME_REVOCATION_FAILED",
512
+ "REALTIME_ADAPTER_MISSING",
513
+ "REALTIME_ADAPTER_COMMAND_FAILED",
514
+ "REALTIME_COMPOSITE_PARTIAL_FAILURE",
515
+ "REALTIME_SERVER_NOT_ATTACHED"
516
+ ];
517
+ function logEvent(logger, level, event, message, fields = {}, error) {
518
+ logger[level]({ event, message, ...fields, ...error === void 0 ? {} : { err: error } });
519
+ }
214
520
 
215
521
  // src/server/utils/describe-error.ts
216
522
  function describeError(reason) {
@@ -224,13 +530,32 @@ function describeError(reason) {
224
530
 
225
531
  // src/server/utils/report-delivery-failure.ts
226
532
  function reportDeliveryFailure(logger, hooks, failure, what) {
227
- logger.warn(`${failure.code} op=${failure.op}: ${what}: ${describeError(failure.error)}`);
533
+ logEvent(
534
+ logger,
535
+ "warn",
536
+ "REALTIME_DELIVERY_FAILED",
537
+ `${what}`,
538
+ {
539
+ code: failure.code,
540
+ op: failure.op
541
+ },
542
+ failure.error
543
+ );
228
544
  const reported = {
229
545
  ...failure,
230
546
  error: failure.error instanceof Error ? failure.error : new Error(describeError(failure.error))
231
547
  };
232
548
  void Promise.resolve().then(() => hooks?.onDeliveryFailure?.(reported)).catch((err) => {
233
- logger.warn(`onDeliveryFailure hook failed: ${describeError(err)}`);
549
+ logEvent(
550
+ logger,
551
+ "warn",
552
+ "REALTIME_HOOK_FAILED",
553
+ `onDeliveryFailure hook failed`,
554
+ {
555
+ hook: "onDeliveryFailure"
556
+ },
557
+ err
558
+ );
234
559
  });
235
560
  }
236
561
 
@@ -275,8 +600,12 @@ var OfflineQueueDeliveryService = class {
275
600
  timeouts = windowedReport(
276
601
  () => 0,
277
602
  (count) => {
278
- this.logger.warn(
279
- `reconnects given up on since the last report: ${count}, because the offline queue did not answer in ${this.timeoutMs} ms or already had ${this.maxPending} reads waiting`
603
+ logEvent(
604
+ this.logger,
605
+ "warn",
606
+ "REALTIME_RECONNECTS_GIVEN_UP",
607
+ `reconnects given up on since the last report: ${count}, because the offline queue did not answer in ${this.timeoutMs} ms or already had ${this.maxPending} reads waiting`,
608
+ { count, timeoutMs: this.timeoutMs, maxPending: this.maxPending }
280
609
  );
281
610
  }
282
611
  );
@@ -305,8 +634,12 @@ var OfflineQueueDeliveryService = class {
305
634
  return { events: [], degraded: true };
306
635
  }
307
636
  if (events.length === RETRIEVE_LIMIT) {
308
- this.logger.warn(
309
- `Offline queue retrieve hit the ${RETRIEVE_LIMIT}-event limit for user; older gap events may be dropped.`
637
+ logEvent(
638
+ this.logger,
639
+ "warn",
640
+ "REALTIME_OFFLINE_QUEUE_LIMIT",
641
+ `Offline queue retrieve hit the ${RETRIEVE_LIMIT}-event limit for user; older gap events may be dropped.`,
642
+ { limit: RETRIEVE_LIMIT }
310
643
  );
311
644
  }
312
645
  return { events, degraded: false };
@@ -317,7 +650,14 @@ var OfflineQueueDeliveryService = class {
317
650
  try {
318
651
  await this.storage.acknowledge(userId, lastId);
319
652
  } catch (err) {
320
- this.logger.warn(`Offline queue acknowledge failed: ${describeError(err)}`);
653
+ logEvent(
654
+ this.logger,
655
+ "warn",
656
+ "REALTIME_OFFLINE_QUEUE_ACK_FAILED",
657
+ `Offline queue acknowledge failed`,
658
+ {},
659
+ err
660
+ );
321
661
  }
322
662
  }
323
663
  async retrieveAppended(userId, lastEventId, read) {
@@ -424,7 +764,7 @@ function refuseReservedRoom(operation, roomId) {
424
764
  }
425
765
 
426
766
  // src/server/utils/admit-rooms.ts
427
- function refuse(detail) {
767
+ function refuse2(detail) {
428
768
  throw realtimeError(
429
769
  REALTIME_ERROR_CODES.AUTH_FAILED,
430
770
  `the authenticator returned rooms that are not valid: ${detail}. Fix the authenticator; the limits are bounds against abuse and apply to this field only.`
@@ -433,11 +773,11 @@ function refuse(detail) {
433
773
  function admitRooms(auth) {
434
774
  const { rooms } = auth;
435
775
  if (rooms === void 0) return auth;
436
- if (!Array.isArray(rooms)) refuse("`rooms` is not an array");
776
+ if (!Array.isArray(rooms)) refuse2("`rooms` is not an array");
437
777
  const admitted = [];
438
778
  for (const room of rooms) {
439
779
  if (admitted.length === ADMISSION_ROOM_LIMITS.MAX_ROOMS) {
440
- refuse(
780
+ refuse2(
441
781
  `more than ${ADMISSION_ROOM_LIMITS.MAX_ROOMS} rooms: the limit is ${ADMISSION_ROOM_LIMITS.MAX_ROOMS}`
442
782
  );
443
783
  }
@@ -445,13 +785,13 @@ function admitRooms(auth) {
445
785
  }
446
786
  for (const room of admitted) {
447
787
  if (typeof room !== "string" || room.trim().length === 0) {
448
- refuse("every room must be a non-blank string");
788
+ refuse2("every room must be a non-blank string");
449
789
  }
450
790
  if (room.length > ADMISSION_ROOM_LIMITS.MAX_ROOM_NAME_LENGTH) {
451
- refuse(`a room name is longer than ${ADMISSION_ROOM_LIMITS.MAX_ROOM_NAME_LENGTH} characters`);
791
+ refuse2(`a room name is longer than ${ADMISSION_ROOM_LIMITS.MAX_ROOM_NAME_LENGTH} characters`);
452
792
  }
453
793
  const reserved = reservedRoomPrefix(room);
454
- if (reserved !== void 0) refuse(`a room name starts with the reserved prefix "${reserved}"`);
794
+ if (reserved !== void 0) refuse2(`a room name starts with the reserved prefix "${reserved}"`);
455
795
  }
456
796
  return { ...auth, rooms: Object.freeze(admitted) };
457
797
  }
@@ -523,6 +863,7 @@ var AuthenticationUnavailableError = class extends Error {
523
863
  this.reason = reason;
524
864
  }
525
865
  reason;
866
+ code = REALTIME_ERROR_CODES.TRANSPORT_UNAVAILABLE;
526
867
  };
527
868
  var AuthenticationGate = class {
528
869
  constructor(options, authenticator) {
@@ -538,8 +879,17 @@ var AuthenticationGate = class {
538
879
  refusals = windowedReport(
539
880
  () => ({ saturated: 0, timeout: 0 }),
540
881
  ({ saturated, timeout }) => {
541
- this.logger.warn(
542
- `handshakes refused since the last report: ${saturated} because ${this.maxPending} were already waiting for the authenticator, ${timeout} because it did not answer in ${this.timeoutMs} ms`
882
+ logEvent(
883
+ this.logger,
884
+ "warn",
885
+ "REALTIME_HANDSHAKES_REFUSED",
886
+ `handshakes refused since the last report: ${saturated} because ${this.maxPending} were already waiting for the authenticator, ${timeout} because it did not answer in ${this.timeoutMs} ms`,
887
+ {
888
+ saturated,
889
+ timedOut: timeout,
890
+ maxPendingHandshakes: this.maxPending,
891
+ authenticateTimeoutMs: this.timeoutMs
892
+ }
543
893
  );
544
894
  }
545
895
  );
@@ -655,6 +1005,7 @@ var ConnectionLimitError = class extends Error {
655
1005
  this.limit = limit;
656
1006
  }
657
1007
  limit;
1008
+ code = REALTIME_ERROR_CODES.TRANSPORT_UNAVAILABLE;
658
1009
  };
659
1010
  var UNBOUNDED_TICKET = {
660
1011
  release: () => void 0,
@@ -674,8 +1025,12 @@ var ConnectionAdmission = class {
674
1025
  refusals = windowedReport(
675
1026
  () => 0,
676
1027
  (count) => {
677
- this.logger.warn(
678
- `connections refused since the last report: ${count}, because the instance already holds ${this.max} (maxConnections)`
1028
+ logEvent(
1029
+ this.logger,
1030
+ "warn",
1031
+ "REALTIME_CONNECTIONS_REFUSED",
1032
+ `connections refused since the last report: ${count}, because the instance already holds ${this.max} (maxConnections)`,
1033
+ { count, maxConnections: this.max }
679
1034
  );
680
1035
  }
681
1036
  );
@@ -924,7 +1279,7 @@ var HeartbeatService = class {
924
1279
  if (intervalMs < HEARTBEAT_MIN_MS || intervalMs > HEARTBEAT_MAX_MS) {
925
1280
  throw realtimeError(
926
1281
  REALTIME_ERROR_CODES.INVALID_OPTIONS,
927
- `heartbeatMs must be between ${HEARTBEAT_MIN_MS} and ${HEARTBEAT_MAX_MS} ms (got ${intervalMs})`
1282
+ `heartbeatMs must be between ${HEARTBEAT_MIN_MS} and ${HEARTBEAT_MAX_MS} ms, received ${describeReceived(intervalMs)}`
928
1283
  );
929
1284
  }
930
1285
  this.stop(connectionId);
@@ -1059,7 +1414,7 @@ var StallWatch = class {
1059
1414
  // src/server/transports/sse/sse.transport.ts
1060
1415
  var _shuttingDown;
1061
1416
  var SseTransport = class {
1062
- constructor(connections, rooms, replayBuffer, idGen, heartbeat, gate, pubsub, hooks, options, instanceId, offlineQueue, admission) {
1417
+ constructor(connections, rooms, replayBuffer, idGen, heartbeat, gate, pubsub, hooks, options, instanceId, offlineQueue, admission, tally) {
1063
1418
  this.connections = connections;
1064
1419
  this.rooms = rooms;
1065
1420
  this.replayBuffer = replayBuffer;
@@ -1072,6 +1427,7 @@ var SseTransport = class {
1072
1427
  this.instanceId = instanceId;
1073
1428
  this.offlineQueue = offlineQueue;
1074
1429
  this.admission = admission;
1430
+ this.tally = tally;
1075
1431
  __publicField(this, "kind", "sse");
1076
1432
  __publicField(this, "logger", new Logger(SseTransport.name));
1077
1433
  __privateAdd(this, _shuttingDown, false);
@@ -1089,6 +1445,7 @@ var SseTransport = class {
1089
1445
  instanceId;
1090
1446
  offlineQueue;
1091
1447
  admission;
1448
+ tally;
1092
1449
  onModuleDestroy() {
1093
1450
  __privateSet(this, _shuttingDown, true);
1094
1451
  }
@@ -1175,7 +1532,18 @@ var SseTransport = class {
1175
1532
  }),
1176
1533
  this.options.hookTimeoutMs ?? DEFAULT_HOOK_TIMEOUT_MS
1177
1534
  );
1178
- if (failed) this.logger.error(`onDisconnect hook failed: ${describeError(failed.error)}`);
1535
+ if (failed) {
1536
+ logEvent(
1537
+ this.logger,
1538
+ "error",
1539
+ "REALTIME_HOOK_FAILED",
1540
+ `onDisconnect hook failed`,
1541
+ {
1542
+ hook: "onDisconnect"
1543
+ },
1544
+ failed.error
1545
+ );
1546
+ }
1179
1547
  }
1180
1548
  getReplayEvents(userId, lastEventId) {
1181
1549
  return this.replayBuffer.since(userId, lastEventId);
@@ -1277,15 +1645,18 @@ var SseTransport = class {
1277
1645
  }
1278
1646
  emitToUserLocal(userId, event, data, id) {
1279
1647
  const message = this.buildMessage(id, event, data);
1648
+ this.tally?.emitted("sse");
1280
1649
  this.replayBuffer.append(userId, message);
1281
1650
  for (const conn of this.connections.byUser(userId, "sse")) this.deliver(conn, message);
1282
1651
  }
1283
1652
  emitToTenantLocal(tenantId, event, data, id) {
1284
1653
  const message = this.buildMessage(id, event, data);
1654
+ this.tally?.emitted("sse");
1285
1655
  for (const conn of this.connections.byTenant(tenantId, "sse")) this.deliver(conn, message);
1286
1656
  }
1287
1657
  emitToRoomLocal(roomId, event, data, id) {
1288
1658
  const message = this.buildMessage(id, event, data);
1659
+ this.tally?.emitted("sse");
1289
1660
  for (const connectionId of this.rooms.members(roomId)) {
1290
1661
  const conn = this.connections.get(connectionId);
1291
1662
  if (conn && conn.transport === "sse") this.deliver(conn, message);
@@ -1293,6 +1664,7 @@ var SseTransport = class {
1293
1664
  }
1294
1665
  broadcastLocal(event, data, id) {
1295
1666
  const message = this.buildMessage(id, event, data);
1667
+ this.tally?.emitted("sse");
1296
1668
  for (const conn of this.connections.allByTransport("sse")) this.deliver(conn, message);
1297
1669
  }
1298
1670
  async disconnectLocal(connectionId, reason) {
@@ -1315,7 +1687,16 @@ var SseTransport = class {
1315
1687
  }
1316
1688
  conn.subject?.next(message);
1317
1689
  } catch (error) {
1318
- this.logger.warn(`SSE delivery failed for ${conn.connectionId}: ${describeError(error)}`);
1690
+ logEvent(
1691
+ this.logger,
1692
+ "warn",
1693
+ "REALTIME_DELIVERY_FAILED",
1694
+ `SSE delivery failed`,
1695
+ {
1696
+ connectionId: conn.connectionId
1697
+ },
1698
+ error
1699
+ );
1319
1700
  }
1320
1701
  }
1321
1702
  track(params) {
@@ -1342,13 +1723,23 @@ var SseTransport = class {
1342
1723
  }
1343
1724
  }
1344
1725
  cutSlowConsumer(connectionId, why, tracked) {
1345
- this.logger.warn(
1346
- `${REALTIME_ERROR_CODES.SLOW_CONSUMER}: closing SSE connection ${connectionId}, ${why} (${tracked.backlog.queuedEvents} events, ${tracked.backlog.queuedBytes} bytes queued, ${tracked.probe.buffered()} bytes held by the response)`
1347
- );
1726
+ this.tally?.evicted("slow_consumer");
1727
+ this.tally?.slowConsumerDropped();
1728
+ logEvent(this.logger, "warn", "REALTIME_SLOW_CONSUMER", `closing an SSE connection, ${why}`, {
1729
+ connectionId,
1730
+ queuedEvents: tracked.backlog.queuedEvents,
1731
+ queuedBytes: tracked.backlog.queuedBytes,
1732
+ heldBytes: tracked.probe.buffered()
1733
+ });
1348
1734
  this.disconnectLocal(connectionId, REALTIME_ERROR_CODES.SLOW_CONSUMER).catch(
1349
1735
  (error) => {
1350
- this.logger.warn(
1351
- `Closing slow SSE connection ${connectionId} failed: ${describeError(error)}`
1736
+ logEvent(
1737
+ this.logger,
1738
+ "warn",
1739
+ "REALTIME_DISCONNECT_FAILED",
1740
+ `Closing a slow SSE connection failed`,
1741
+ { connectionId },
1742
+ error
1352
1743
  );
1353
1744
  }
1354
1745
  );
@@ -1379,6 +1770,7 @@ var SseTransport = class {
1379
1770
  let userConnections = this.connections.byUser(userId, "sse");
1380
1771
  while (userConnections.length > max) {
1381
1772
  const oldest = userConnections.reduce((a, b) => a.connectedAt <= b.connectedAt ? a : b);
1773
+ this.tally?.evicted("per_user_cap");
1382
1774
  await this.disconnectLocal(oldest.connectionId, REALTIME_ERROR_CODES.TOO_MANY_CONNECTIONS);
1383
1775
  userConnections = this.connections.byUser(userId, "sse");
1384
1776
  }
@@ -1400,7 +1792,9 @@ SseTransport = __decorateClass([
1400
1792
  __decorateParam(10, Optional()),
1401
1793
  __decorateParam(10, Inject(REALTIME_OFFLINE_QUEUE_TOKEN)),
1402
1794
  __decorateParam(11, Optional()),
1403
- __decorateParam(11, Inject(ConnectionAdmission))
1795
+ __decorateParam(11, Inject(ConnectionAdmission)),
1796
+ __decorateParam(12, Optional()),
1797
+ __decorateParam(12, Inject(RealtimeMetricsTally))
1404
1798
  ], SseTransport);
1405
1799
 
1406
1800
  // src/server/transports/sse/response-close.ts
@@ -1474,18 +1868,22 @@ function buildMeta(record) {
1474
1868
  };
1475
1869
  }
1476
1870
  var SseSubscriptionHandler = class {
1477
- constructor(transport, heartbeat, options, hooks, offlineDelivery) {
1871
+ constructor(transport, heartbeat, options, hooks, offlineDelivery, tally, tracing) {
1478
1872
  this.transport = transport;
1479
1873
  this.heartbeat = heartbeat;
1480
1874
  this.options = options;
1481
1875
  this.hooks = hooks;
1482
1876
  this.offlineDelivery = offlineDelivery;
1877
+ this.tally = tally;
1878
+ this.tracing = tracing;
1483
1879
  }
1484
1880
  transport;
1485
1881
  heartbeat;
1486
1882
  options;
1487
1883
  hooks;
1488
1884
  offlineDelivery;
1885
+ tally;
1886
+ tracing;
1489
1887
  logger = new Logger(SseSubscriptionHandler.name);
1490
1888
  authenticated = /* @__PURE__ */ new WeakMap();
1491
1889
  resolveAndValidateIdentity(auth) {
@@ -1494,7 +1892,15 @@ var SseSubscriptionHandler = class {
1494
1892
  assertIdentityIsNotBlank(resolvedAuth);
1495
1893
  resolvedAuth = admitRooms(resolvedAuth);
1496
1894
  } catch (err) {
1497
- this.logger.error(`SSE connection refused \u2014 responding 500: ${describeError(err)}`);
1895
+ this.tally?.refused("error");
1896
+ logEvent(
1897
+ this.logger,
1898
+ "error",
1899
+ "REALTIME_HANDSHAKE_FAILED",
1900
+ `SSE connection refused \u2014 responding 500`,
1901
+ {},
1902
+ err
1903
+ );
1498
1904
  throw new InternalServerErrorException();
1499
1905
  }
1500
1906
  return resolvedAuth;
@@ -1529,6 +1935,7 @@ var SseSubscriptionHandler = class {
1529
1935
  }
1530
1936
  refuseDuringShutdown() {
1531
1937
  if (this.transport.shuttingDown) {
1938
+ this.tally?.refused("unavailable");
1532
1939
  throw new ServiceUnavailableException(REALTIME_ERROR_CODES.TRANSPORT_UNAVAILABLE);
1533
1940
  }
1534
1941
  }
@@ -1566,16 +1973,29 @@ var SseSubscriptionHandler = class {
1566
1973
  }
1567
1974
  }
1568
1975
  toClientError(err, what) {
1569
- if (err instanceof AuthenticationUnavailableError || err instanceof ConnectionLimitError) {
1976
+ if (err instanceof ConnectionLimitError) {
1977
+ this.tally?.refused("limit");
1570
1978
  return new ServiceUnavailableException();
1571
1979
  }
1980
+ if (err instanceof AuthenticationUnavailableError) {
1981
+ this.tally?.refused("unavailable");
1982
+ return new ServiceUnavailableException();
1983
+ }
1984
+ if (err instanceof HttpException && err.getStatus() === HttpStatus.UNAUTHORIZED) {
1985
+ this.tally?.refused("unauthorized");
1986
+ }
1572
1987
  return err instanceof HttpException ? err : this.serverError(err, what);
1573
1988
  }
1574
1989
  serverError(err, what) {
1575
- this.logger.error(`${what} \u2014 responding 500: ${describeError(err)}`);
1990
+ this.tally?.refused("error");
1991
+ logEvent(this.logger, "error", "REALTIME_HANDSHAKE_FAILED", `${what} \u2014 responding 500`, {}, err);
1576
1992
  return new InternalServerErrorException();
1577
1993
  }
1578
- async authenticateRequest(req, res) {
1994
+ authenticateRequest(req, res) {
1995
+ const run = () => this.admitAndAuthenticate(req, res);
1996
+ return this.tracing ? this.tracing.span("realtime.handshake", { "bymax.realtime.transport": "sse" }, run) : run();
1997
+ }
1998
+ async admitAndAuthenticate(req, res) {
1579
1999
  const held = this.transport.admit();
1580
2000
  const detach = onResponseClose(res, () => ticket.release());
1581
2001
  const ticket = {
@@ -1709,7 +2129,14 @@ var SseSubscriptionHandler = class {
1709
2129
  fireHook(invoke, onFailure) {
1710
2130
  void runHook(invoke).then((failed) => {
1711
2131
  if (!failed) return;
1712
- this.logger.warn(`Lifecycle hook failed: ${describeError(failed.error)}`);
2132
+ logEvent(
2133
+ this.logger,
2134
+ "warn",
2135
+ "REALTIME_HOOK_FAILED",
2136
+ `Lifecycle hook failed`,
2137
+ {},
2138
+ failed.error
2139
+ );
1713
2140
  onFailure?.();
1714
2141
  });
1715
2142
  }
@@ -1722,7 +2149,11 @@ SseSubscriptionHandler = __decorateClass([
1722
2149
  __decorateParam(3, Optional()),
1723
2150
  __decorateParam(3, Inject(REALTIME_HOOKS_TOKEN)),
1724
2151
  __decorateParam(4, Optional()),
1725
- __decorateParam(4, Inject(OfflineQueueDeliveryService))
2152
+ __decorateParam(4, Inject(OfflineQueueDeliveryService)),
2153
+ __decorateParam(5, Optional()),
2154
+ __decorateParam(5, Inject(RealtimeMetricsTally)),
2155
+ __decorateParam(6, Optional()),
2156
+ __decorateParam(6, Inject(RealtimeTracing))
1726
2157
  ], SseSubscriptionHandler);
1727
2158
 
1728
2159
  // src/server/utils/normalize-endpoint-path.ts
@@ -1773,12 +2204,14 @@ function createSseController(endpoint) {
1773
2204
  return DynamicSseController;
1774
2205
  }
1775
2206
  var RealtimeService = class {
1776
- constructor(transport, pubsub) {
2207
+ constructor(transport, pubsub, tally) {
1777
2208
  this.transport = transport;
1778
2209
  this.pubsub = pubsub;
2210
+ this.tally = tally;
1779
2211
  }
1780
2212
  transport;
1781
2213
  pubsub;
2214
+ tally;
1782
2215
  isPubSubReady() {
1783
2216
  if (this.transport.kind === "websocket") return true;
1784
2217
  return this.pubsub?.isSubscribed?.() ?? true;
@@ -1804,15 +2237,18 @@ var RealtimeService = class {
1804
2237
  refuseReservedRoom("leaveRoom", roomId);
1805
2238
  return this.transport.leaveRoom(connectionId, roomId);
1806
2239
  }
1807
- disconnect(connectionId, reason) {
1808
- return this.transport.disconnect(connectionId, reason);
2240
+ async disconnect(connectionId, reason) {
2241
+ await this.transport.disconnect(connectionId, reason);
2242
+ this.tally?.evicted("revoked");
1809
2243
  }
1810
2244
  };
1811
2245
  RealtimeService = __decorateClass([
1812
2246
  Injectable(),
1813
2247
  __decorateParam(0, Inject(REALTIME_TRANSPORT_TOKEN)),
1814
2248
  __decorateParam(1, Optional()),
1815
- __decorateParam(1, Inject(REALTIME_PUBSUB_TOKEN))
2249
+ __decorateParam(1, Inject(REALTIME_PUBSUB_TOKEN)),
2250
+ __decorateParam(2, Optional()),
2251
+ __decorateParam(2, Inject(RealtimeMetricsTally))
1816
2252
  ], RealtimeService);
1817
2253
 
1818
2254
  // src/server/utils/semaphore.ts
@@ -1846,31 +2282,55 @@ function resolvePolicy(raw) {
1846
2282
  };
1847
2283
  }
1848
2284
  var ReauthenticationService = class {
1849
- constructor(connections, realtime, auth, options, hooks) {
2285
+ constructor(connections, realtime, auth, options, hooks, tracing) {
1850
2286
  this.connections = connections;
1851
2287
  this.realtime = realtime;
1852
2288
  this.auth = auth;
1853
2289
  this.hooks = hooks;
2290
+ this.tracing = tracing;
1854
2291
  this.policy = resolvePolicy(options.reauthenticationPolicy);
2292
+ this.declared = options.reauthenticationPolicy;
1855
2293
  this.slots = new Semaphore(this.policy.concurrency);
1856
2294
  }
1857
2295
  connections;
1858
2296
  realtime;
1859
2297
  auth;
1860
2298
  hooks;
2299
+ tracing;
1861
2300
  logger = new Logger(ReauthenticationService.name);
1862
2301
  timer = null;
1863
2302
  policy;
2303
+ declared;
1864
2304
  inFlight = /* @__PURE__ */ new Set();
1865
2305
  slots;
2306
+ warnIfCacheOutlivesInterval() {
2307
+ const { cacheTtlMs, intervalSeconds } = this.declared ?? {};
2308
+ if (cacheTtlMs === void 0 || intervalSeconds === void 0) return;
2309
+ if (cacheTtlMs <= intervalSeconds * 1e3) return;
2310
+ logEvent(
2311
+ this.logger,
2312
+ "warn",
2313
+ "REALTIME_REAUTH_CACHE_WEAKENS_POLICY",
2314
+ `reauthenticationPolicy.cacheTtlMs (${cacheTtlMs} ms) exceeds intervalSeconds*1000 (${intervalSeconds * 1e3} ms): the positive reauth cache outlives the interval, so revalidate is skipped on ticks within the cache window \u2014 reauthentication is effectively weakened`,
2315
+ { cacheTtlMs, intervalMs: intervalSeconds * 1e3 }
2316
+ );
2317
+ }
1866
2318
  onModuleInit() {
1867
2319
  if (!this.auth.revalidate) {
1868
2320
  this.logger.log("Authenticator does not implement revalidate() \u2014 reauthentication disabled");
1869
2321
  return;
1870
2322
  }
2323
+ this.warnIfCacheOutlivesInterval();
1871
2324
  this.timer = setInterval(() => {
1872
2325
  this.runCycle().catch((err) => {
1873
- this.logger.warn(`Reauthentication cycle failed: ${describeError(err)}`);
2326
+ logEvent(
2327
+ this.logger,
2328
+ "warn",
2329
+ "REALTIME_REAUTH_FAILED",
2330
+ `Reauthentication cycle failed`,
2331
+ {},
2332
+ err
2333
+ );
1874
2334
  });
1875
2335
  }, this.policy.intervalSeconds * 1e3);
1876
2336
  this.timer.unref();
@@ -1888,7 +2348,10 @@ var ReauthenticationService = class {
1888
2348
  ...this.connections.allByTransport("sse"),
1889
2349
  ...this.connections.allByTransport("websocket")
1890
2350
  ];
1891
- await Promise.all(connections.map((conn) => this.check(conn, now)));
2351
+ const run = async () => {
2352
+ await Promise.all(connections.map((conn) => this.check(conn, now)));
2353
+ };
2354
+ await (this.tracing ? this.tracing.span("realtime.reauthenticate", {}, run) : run());
1892
2355
  }
1893
2356
  async check(conn, now) {
1894
2357
  if (this.inFlight.has(conn.connectionId)) return;
@@ -1925,7 +2388,14 @@ var ReauthenticationService = class {
1925
2388
  }
1926
2389
  await this.revoke(conn);
1927
2390
  } catch (err) {
1928
- this.logger.warn(`Reauthentication errored for ${conn.connectionId}: ${describeError(err)}`);
2391
+ logEvent(
2392
+ this.logger,
2393
+ "warn",
2394
+ "REALTIME_REAUTH_FAILED",
2395
+ `Reauthentication errored`,
2396
+ { connectionId: conn.connectionId },
2397
+ err
2398
+ );
1929
2399
  await this.revoke(conn);
1930
2400
  }
1931
2401
  }
@@ -1949,8 +2419,13 @@ var ReauthenticationService = class {
1949
2419
  try {
1950
2420
  await this.bounded("revocation", () => this.handleFailure(conn));
1951
2421
  } catch (err) {
1952
- this.logger.warn(
1953
- `Revocation of ${conn.connectionId} failed, retrying next cycle: ${describeError(err)}`
2422
+ logEvent(
2423
+ this.logger,
2424
+ "warn",
2425
+ "REALTIME_REVOCATION_FAILED",
2426
+ `Revocation failed, retrying next cycle`,
2427
+ { connectionId: conn.connectionId },
2428
+ err
1954
2429
  );
1955
2430
  }
1956
2431
  }
@@ -1971,15 +2446,27 @@ var ReauthenticationService = class {
1971
2446
  })
1972
2447
  ).then((failed) => {
1973
2448
  if (failed) {
1974
- this.logger.warn(`onReauthenticationFailed hook failed: ${describeError(failed.error)}`);
2449
+ logEvent(
2450
+ this.logger,
2451
+ "warn",
2452
+ "REALTIME_HOOK_FAILED",
2453
+ `onReauthenticationFailed hook failed`,
2454
+ { hook: "onReauthenticationFailed" },
2455
+ failed.error
2456
+ );
1975
2457
  }
1976
2458
  });
1977
2459
  await this.realtime.disconnect(conn.connectionId, REALTIME_ERROR_CODES.REAUTHENTICATION_FAILED);
1978
2460
  }
1979
2461
  notify(conn) {
1980
2462
  const failed = (err) => {
1981
- this.logger.warn(
1982
- `Reauthentication notification for ${conn.connectionId} failed, disconnecting anyway: ${describeError(err)}`
2463
+ logEvent(
2464
+ this.logger,
2465
+ "warn",
2466
+ "REALTIME_REAUTH_FAILED",
2467
+ `Reauthentication notification failed, disconnecting anyway`,
2468
+ { connectionId: conn.connectionId },
2469
+ err
1983
2470
  );
1984
2471
  };
1985
2472
  try {
@@ -1998,7 +2485,9 @@ ReauthenticationService = __decorateClass([
1998
2485
  __decorateParam(2, Inject(REALTIME_AUTHENTICATOR_TOKEN)),
1999
2486
  __decorateParam(3, Inject(REALTIME_OPTIONS_TOKEN)),
2000
2487
  __decorateParam(4, Optional()),
2001
- __decorateParam(4, Inject(REALTIME_HOOKS_TOKEN))
2488
+ __decorateParam(4, Inject(REALTIME_HOOKS_TOKEN)),
2489
+ __decorateParam(5, Optional()),
2490
+ __decorateParam(5, Inject(RealtimeTracing))
2002
2491
  ], ReauthenticationService);
2003
2492
 
2004
2493
  // src/server/composition/realtime-module.factory.ts
@@ -2006,6 +2495,7 @@ var DEFAULT_ASYNC_SSE_ENDPOINT = "/events";
2006
2495
  var EXPORTED_TOKENS = [
2007
2496
  RealtimeService,
2008
2497
  ConnectionRegistry,
2498
+ RealtimeMetricsTally,
2009
2499
  REALTIME_OPTIONS_TOKEN,
2010
2500
  REALTIME_INSTANCE_ID_TOKEN,
2011
2501
  REALTIME_AUTHENTICATOR_TOKEN,
@@ -2025,7 +2515,9 @@ var SHARED_SERVICES = [
2025
2515
  ReauthenticationService,
2026
2516
  OfflineQueueDeliveryService,
2027
2517
  AuthenticationGate,
2028
- ConnectionAdmission
2518
+ ConnectionAdmission,
2519
+ RealtimeMetricsTally,
2520
+ RealtimeTracing
2029
2521
  ];
2030
2522
  function assertModeSupported(wiring, mode, moduleName) {
2031
2523
  if (wiring.modes.includes(mode)) return;
@@ -2039,7 +2531,10 @@ function assertModeSupported(wiring, mode, moduleName) {
2039
2531
  function warnIfSingleInstance(pubsub, transport, logger) {
2040
2532
  if (transport === "websocket") return;
2041
2533
  if (!pubsub && process.env["NODE_ENV"] === "production") {
2042
- logger.warn(
2534
+ logEvent(
2535
+ logger,
2536
+ "warn",
2537
+ "REALTIME_PUBSUB_NOT_PROVIDED",
2043
2538
  "No IRealtimePubSub provided in production \u2014 single-instance only. Provide a Redis-backed IRealtimePubSub for horizontal scaling."
2044
2539
  );
2045
2540
  }
@@ -2056,7 +2551,9 @@ function buildCommonProviders(resolved, instanceId) {
2056
2551
  ...SHARED_SERVICES
2057
2552
  ];
2058
2553
  }
2059
- function composeForRoot(moduleClass, wiring, logger, options) {
2554
+ function composeForRoot(moduleClass, wiring, logger, raw) {
2555
+ assertOptionsObject(raw, moduleClass.name);
2556
+ const options = dropUnset(raw);
2060
2557
  validateOptions(options);
2061
2558
  assertModeSupported(wiring, options.transport, moduleClass.name);
2062
2559
  const resolved = applyDefaults(options);
@@ -2075,7 +2572,7 @@ function assertSseEndpointApplies(asyncOptions, moduleName) {
2075
2572
  if (asyncOptions.sseEndpoint === void 0 || asyncOptions.transport !== "websocket") return;
2076
2573
  throw realtimeError(
2077
2574
  REALTIME_ERROR_CODES.INVALID_OPTIONS,
2078
- `sseEndpoint '${asyncOptions.sseEndpoint}' was set but transport 'websocket' registers no SSE controller \u2014 use 'both' to serve SSE too`,
2575
+ `sseEndpoint was set but transport 'websocket' registers no SSE controller \u2014 use 'both' to serve SSE too`,
2079
2576
  { who: moduleName }
2080
2577
  );
2081
2578
  }
@@ -2083,34 +2580,39 @@ function bindSseEndpoint(resolved, declared, bound, moduleName) {
2083
2580
  if (declared !== void 0 && normalizeEndpointPath(declared) !== normalizeEndpointPath(bound)) {
2084
2581
  throw realtimeError(
2085
2582
  REALTIME_ERROR_CODES.INVALID_OPTIONS,
2086
- `the factory resolved sse.endpoint '${declared}' but forRootAsync bound the SSE route to '${bound}' \u2014 controllers are registered before the factory runs, so declare the path as 'sseEndpoint' on the forRootAsync registration itself`,
2583
+ `the factory resolved an sse.endpoint that differs from the SSE route forRootAsync bound \u2014 controllers are registered before the factory runs, so declare the path as 'sseEndpoint' on the forRootAsync registration itself`,
2087
2584
  { who: moduleName }
2088
2585
  );
2089
2586
  }
2090
2587
  return Object.freeze({ ...resolved, sse: { ...resolved.sse, endpoint: bound } });
2091
2588
  }
2092
2589
  function resolveAsyncOptions(raw, declaredMode, instanceId, source, logger, moduleName) {
2093
- if (!raw) {
2590
+ if (raw === void 0 || raw === null) {
2094
2591
  throw realtimeError(REALTIME_ERROR_CODES.INVALID_OPTIONS, `${source} returned nothing`);
2095
2592
  }
2096
- validateOptions(raw);
2097
- if (raw.transport !== declaredMode) {
2593
+ assertOptionsObject(raw, moduleName);
2594
+ const options = dropUnset(raw);
2595
+ validateOptions(options);
2596
+ if (options.transport !== declaredMode) {
2098
2597
  throw realtimeError(
2099
2598
  REALTIME_ERROR_CODES.INVALID_OPTIONS,
2100
- `forRootAsync was registered for transport '${declaredMode}' but the factory resolved '${raw.transport}'`,
2599
+ `forRootAsync was registered for transport '${declaredMode}' but the factory resolved '${options.transport}'`,
2101
2600
  { who: moduleName }
2102
2601
  );
2103
2602
  }
2104
- const resolved = applyDefaults(raw);
2603
+ const resolved = applyDefaults(options);
2105
2604
  logger.log(`Bootstrapped (transport=${resolved.transport}, instanceId=${instanceId})`);
2106
- return resolved;
2605
+ return { resolved, declaredEndpoint: options.sse?.endpoint };
2606
+ }
2607
+ function isSet(pattern) {
2608
+ return pattern !== void 0 && pattern !== null;
2107
2609
  }
2108
2610
  function assertOneFactoryPattern(asyncOptions, moduleName) {
2109
2611
  const patterns = [
2110
2612
  asyncOptions.useFactory,
2111
2613
  asyncOptions.useClass,
2112
2614
  asyncOptions.useExisting
2113
- ].filter((pattern) => pattern !== void 0);
2615
+ ].filter(isSet);
2114
2616
  if (patterns.length === 1) return;
2115
2617
  throw realtimeError(
2116
2618
  REALTIME_ERROR_CODES.INVALID_OPTIONS,
@@ -2119,7 +2621,7 @@ function assertOneFactoryPattern(asyncOptions, moduleName) {
2119
2621
  );
2120
2622
  }
2121
2623
  function buildOptionsProvider(asyncOptions, resolve, factoryToken) {
2122
- if (asyncOptions.useFactory) {
2624
+ if (isSet(asyncOptions.useFactory)) {
2123
2625
  return {
2124
2626
  provide: REALTIME_OPTIONS_TOKEN,
2125
2627
  useFactory: async (...args) => resolve(await asyncOptions.useFactory(...args), "useFactory"),
@@ -2128,10 +2630,18 @@ function buildOptionsProvider(asyncOptions, resolve, factoryToken) {
2128
2630
  }
2129
2631
  return {
2130
2632
  provide: REALTIME_OPTIONS_TOKEN,
2131
- useFactory: async (factory) => resolve(
2132
- await factory.createRealtimeOptions(),
2133
- "createRealtimeOptions"
2134
- ),
2633
+ useFactory: async (factory) => {
2634
+ if (typeof factory?.createRealtimeOptions !== "function") {
2635
+ throw realtimeError(
2636
+ REALTIME_ERROR_CODES.INVALID_OPTIONS,
2637
+ "the provider named by useExisting or useClass must implement createRealtimeOptions"
2638
+ );
2639
+ }
2640
+ return resolve(
2641
+ await factory.createRealtimeOptions(),
2642
+ "createRealtimeOptions"
2643
+ );
2644
+ },
2135
2645
  inject: [asyncOptions.useExisting ?? factoryToken]
2136
2646
  };
2137
2647
  }
@@ -2153,7 +2663,7 @@ function buildOptionDerivedProviders(logger, instanceId) {
2153
2663
  }
2154
2664
  function buildResolver(asyncOptions, instanceId, boundSseEndpoint, logger, moduleName) {
2155
2665
  return (raw, source) => {
2156
- const resolved = resolveAsyncOptions(
2666
+ const { resolved, declaredEndpoint } = resolveAsyncOptions(
2157
2667
  raw,
2158
2668
  asyncOptions.transport,
2159
2669
  instanceId,
@@ -2162,19 +2672,21 @@ function buildResolver(asyncOptions, instanceId, boundSseEndpoint, logger, modul
2162
2672
  moduleName
2163
2673
  );
2164
2674
  if (asyncOptions.transport === "websocket") return resolved;
2165
- return bindSseEndpoint(resolved, raw?.sse?.endpoint, boundSseEndpoint, moduleName);
2675
+ return bindSseEndpoint(resolved, declaredEndpoint, boundSseEndpoint, moduleName);
2166
2676
  };
2167
2677
  }
2168
2678
  function composeForRootAsync(moduleClass, wiring, logger, asyncOptions) {
2169
2679
  const moduleName = moduleClass.name;
2680
+ assertOptionsObject(asyncOptions, moduleName);
2170
2681
  assertOneFactoryPattern(asyncOptions, moduleName);
2171
2682
  assertModeSupported(wiring, asyncOptions.transport, moduleName);
2683
+ assertSseEndpoint("sseEndpoint", asyncOptions.sseEndpoint);
2172
2684
  assertSseEndpointApplies(asyncOptions, moduleName);
2173
2685
  const FACTORY_TOKEN = /* @__PURE__ */ Symbol("REALTIME_OPTIONS_FACTORY");
2174
2686
  const instanceId = randomUUID();
2175
2687
  const boundSseEndpoint = asyncOptions.sseEndpoint ?? DEFAULT_ASYNC_SSE_ENDPOINT;
2176
2688
  const resolve = buildResolver(asyncOptions, instanceId, boundSseEndpoint, logger, moduleName);
2177
- const factoryClassProvider = asyncOptions.useClass ? [{ provide: FACTORY_TOKEN, useClass: asyncOptions.useClass }] : [];
2689
+ const factoryClassProvider = isSet(asyncOptions.useClass) ? [{ provide: FACTORY_TOKEN, useClass: asyncOptions.useClass }] : [];
2178
2690
  const { providers: transportProviders, controllers } = wiring.buildAsync({
2179
2691
  mode: asyncOptions.transport,
2180
2692
  sseEndpoint: boundSseEndpoint
@@ -2213,7 +2725,14 @@ var RealtimePubSubSubscriber = class {
2213
2725
  try {
2214
2726
  await this.unsubscribe();
2215
2727
  } catch (err) {
2216
- this.logger.warn(`Pub/sub unsubscribe failed: ${describeError(err)}`);
2728
+ logEvent(
2729
+ this.logger,
2730
+ "warn",
2731
+ "REALTIME_PUBSUB_UNSUBSCRIBE_FAILED",
2732
+ `Pub/sub unsubscribe failed`,
2733
+ {},
2734
+ err
2735
+ );
2217
2736
  }
2218
2737
  this.unsubscribe = null;
2219
2738
  }
@@ -2221,8 +2740,12 @@ var RealtimePubSubSubscriber = class {
2221
2740
  dropped = windowedReport(
2222
2741
  () => ({ count: 0, last: "none" }),
2223
2742
  ({ count, last }) => {
2224
- this.logger.warn(
2225
- `Pub/sub dropped ${count} message(s) it could not act on since the last report (last: ${last})`
2743
+ logEvent(
2744
+ this.logger,
2745
+ "warn",
2746
+ "REALTIME_PUBSUB_DROPPED",
2747
+ `Pub/sub dropped ${count} message(s) it could not act on since the last report (last: ${last})`,
2748
+ { count, last }
2226
2749
  );
2227
2750
  }
2228
2751
  );
@@ -2250,17 +2773,9 @@ var RealtimePubSubSubscriber = class {
2250
2773
  this.sse.broadcastLocal(a.event, a.data, a.id);
2251
2774
  break;
2252
2775
  }
2253
- case "disconnect": {
2254
- const a = msg.args;
2255
- Promise.resolve(this.sse.disconnectLocal(a.connectionId, a.reason)).catch(
2256
- (err) => {
2257
- this.logger.warn(
2258
- `Remote disconnect of ${a.connectionId} failed: ${describeError(err)}`
2259
- );
2260
- }
2261
- );
2776
+ case "disconnect":
2777
+ this.closeLocal(msg.args);
2262
2778
  break;
2263
- }
2264
2779
  default: {
2265
2780
  msg.op;
2266
2781
  this.drop("unknown op");
@@ -2270,6 +2785,18 @@ var RealtimePubSubSubscriber = class {
2270
2785
  this.drop(String(Object(err).constructor?.name ?? "Error"));
2271
2786
  }
2272
2787
  }
2788
+ closeLocal(a) {
2789
+ Promise.resolve(this.sse.disconnectLocal(a.connectionId, a.reason)).catch((err) => {
2790
+ logEvent(
2791
+ this.logger,
2792
+ "warn",
2793
+ "REALTIME_DISCONNECT_FAILED",
2794
+ "Remote disconnect failed",
2795
+ { connectionId: a.connectionId },
2796
+ err
2797
+ );
2798
+ });
2799
+ }
2273
2800
  drop(last) {
2274
2801
  this.dropped(({ count }) => ({ count: count + 1, last }));
2275
2802
  }
@@ -2363,11 +2890,6 @@ var CANNOT_PUBLISH = /* @__PURE__ */ new Set([
2363
2890
  var PUBLISHER_WAIT_MS = 2e3;
2364
2891
  var PUBLISH_WAIT_MS = 2e3;
2365
2892
  var CONNECTION_OVER = ["ready", "close", "reconnecting", "end"];
2366
- function connectionReason(err) {
2367
- const code = err?.code;
2368
- const text = describeError(err);
2369
- return [typeof code === "string" ? code : "", text].filter(Boolean).join(" ") || String(err);
2370
- }
2371
2893
  var RedisRealtimePubSub = class _RedisRealtimePubSub {
2372
2894
  #pub;
2373
2895
  channel;
@@ -2505,7 +3027,7 @@ var RedisRealtimePubSub = class _RedisRealtimePubSub {
2505
3027
  if (outcome === "subscribed") {
2506
3028
  this.markUp();
2507
3029
  } else {
2508
- this.markDown(connectionReason(outcome.unreachable));
3030
+ this.markDown(void 0, outcome.unreachable);
2509
3031
  first.catch((err) => this.refused(err));
2510
3032
  }
2511
3033
  } catch (err) {
@@ -2531,8 +3053,13 @@ var RedisRealtimePubSub = class _RedisRealtimePubSub {
2531
3053
  const reason = describeError(err);
2532
3054
  if (reason === this.#lastRefusal) return;
2533
3055
  this.#lastRefusal = reason;
2534
- this.logger.warn(
2535
- `${REALTIME_ERROR_CODES.PUBSUB_UNAVAILABLE}: the server refused the subscription to "${this.channel}": ${reason}`
3056
+ logEvent(
3057
+ this.logger,
3058
+ "warn",
3059
+ "REALTIME_PUBSUB_UNAVAILABLE",
3060
+ "the server refused the subscription",
3061
+ {},
3062
+ err
2536
3063
  );
2537
3064
  }
2538
3065
  markUp() {
@@ -2544,20 +3071,29 @@ var RedisRealtimePubSub = class _RedisRealtimePubSub {
2544
3071
  `Subscribed to "${this.channel}"; remote events and revocations reach this instance`
2545
3072
  );
2546
3073
  }
2547
- markDown(reason) {
3074
+ markDown(wording, error) {
2548
3075
  this.#subscribed = false;
2549
3076
  if (this.#outageLogged) return;
2550
3077
  this.#outageLogged = true;
2551
- this.logger.warn(
2552
- `${REALTIME_ERROR_CODES.PUBSUB_UNAVAILABLE}: not subscribed to "${this.channel}": ${reason}. Remote events and revocations will not reach this instance until it subscribes again`
3078
+ logEvent(
3079
+ this.logger,
3080
+ "warn",
3081
+ "REALTIME_PUBSUB_UNAVAILABLE",
3082
+ `not subscribed${wording === void 0 ? "" : `: ${wording}`}. Remote events and revocations will not reach this instance until it subscribes again`,
3083
+ {},
3084
+ error
2553
3085
  );
2554
3086
  }
2555
3087
  reportMalformed() {
2556
3088
  this.malformedDropped++;
2557
3089
  const now = Date.now();
2558
3090
  if (now - this.malformedReportedAt < MALFORMED_REPORT_INTERVAL_MS) return;
2559
- this.logger.warn(
2560
- `${REALTIME_ERROR_CODES.PUBSUB_UNAVAILABLE}: dropped ${this.malformedDropped} malformed payload(s) on "${this.channel}" since the last report`
3091
+ logEvent(
3092
+ this.logger,
3093
+ "warn",
3094
+ "REALTIME_PUBSUB_DROPPED",
3095
+ `dropped ${this.malformedDropped} malformed payload(s) since the last report`,
3096
+ { count: this.malformedDropped, last: "malformed" }
2561
3097
  );
2562
3098
  this.malformedDropped = 0;
2563
3099
  this.malformedReportedAt = now;
@@ -2585,6 +3121,18 @@ var RedisRealtimePubSub = class _RedisRealtimePubSub {
2585
3121
  };
2586
3122
 
2587
3123
  // src/server/offline-queue/redis-offline-queue.ts
3124
+ var MAX_PER_USER_CEILING = 1e5;
3125
+ var TTL_SECONDS_CEILING = 2147483647;
3126
+ function requireInteger(name, value, least, most) {
3127
+ if (typeof value === "number" && Number.isSafeInteger(value) && value >= least && value <= most) {
3128
+ return value;
3129
+ }
3130
+ throw realtimeError(
3131
+ REALTIME_ERROR_CODES.INVALID_OPTIONS,
3132
+ `options.${name} must be an integer >= ${least} and <= ${most}, received ${describeReceived(value)}`,
3133
+ { who: "RedisOfflineQueue" }
3134
+ );
3135
+ }
2588
3136
  var RedisOfflineQueue = class _RedisOfflineQueue {
2589
3137
  #client;
2590
3138
  maxPerUser;
@@ -2592,9 +3140,23 @@ var RedisOfflineQueue = class _RedisOfflineQueue {
2592
3140
  static MS_PAD = 16;
2593
3141
  static COUNTER_PAD = 6;
2594
3142
  constructor(options) {
3143
+ if (!isPlainObject(options)) refuseObject("RedisOfflineQueue", "options", options);
3144
+ if (typeof options.client !== "object" || options.client === null) {
3145
+ refuseObject("RedisOfflineQueue", "options.client", options.client);
3146
+ }
2595
3147
  this.#client = options.client;
2596
- this.maxPerUser = options.maxPerUser ?? 500;
2597
- this.ttlSeconds = options.ttlSeconds ?? 3600;
3148
+ this.maxPerUser = requireInteger(
3149
+ "maxPerUser",
3150
+ options.maxPerUser ?? 500,
3151
+ 1,
3152
+ MAX_PER_USER_CEILING
3153
+ );
3154
+ this.ttlSeconds = requireInteger(
3155
+ "ttlSeconds",
3156
+ options.ttlSeconds ?? 3600,
3157
+ 1,
3158
+ TTL_SECONDS_CEILING
3159
+ );
2598
3160
  }
2599
3161
  key(userId) {
2600
3162
  return `bymax:oq:${userId}`;
@@ -2647,4 +3209,4 @@ var RedisOfflineQueue = class _RedisOfflineQueue {
2647
3209
  }
2648
3210
  };
2649
3211
 
2650
- export { ADMISSION_ROOM_LIMITS, AuthenticationGate, AuthenticationUnavailableError, BymaxRealtimeModule, ConnectionAdmission, ConnectionLimitError, ConnectionRegistry, DEFAULT_HOOK_TIMEOUT_MS, EventIdGenerator, EventReplayBuffer, HeartbeatService, InMemoryPubSub, OfflineQueueDeliveryService, REALTIME_AUTHENTICATOR_TOKEN, REALTIME_ERROR_CODES, REALTIME_HOOKS_TOKEN, REALTIME_INSTANCE_ID_TOKEN, REALTIME_OFFLINE_QUEUE_TOKEN, REALTIME_OPTIONS_TOKEN, REALTIME_PRESENCE_TOKEN, REALTIME_PUBSUB_TOKEN, REALTIME_TRANSPORT_TOKEN, RESERVED_EVENT_NAMES, ROOM_PREFIXES, RealtimePubSubSubscriber, RealtimeService, ReauthenticationService, RedisOfflineQueue, RedisRealtimePubSub, RoomRegistry, SseSubscriptionHandler, SseTransport, UNBOUNDED_TICKET, admitRooms, assertIdentityIsNotBlank, composeForRoot, composeForRootAsync, composeRoomId, createSseController, describeError, parseCookieHeader, quitWithin, realtimeError, refuseReservedRoom, reportDeliveryFailure, requireRoomName, resolveAuthTenant, runHook, sseWiring, unavailableError };
3212
+ export { ADMISSION_ROOM_LIMITS, AuthenticationGate, AuthenticationUnavailableError, BymaxRealtimeModule, ConnectionAdmission, ConnectionLimitError, ConnectionRegistry, DEFAULT_HOOK_TIMEOUT_MS, EVICTION_REASONS, EventIdGenerator, EventReplayBuffer, HeartbeatService, InMemoryPubSub, OfflineQueueDeliveryService, REALTIME_AUTHENTICATOR_TOKEN, REALTIME_ERROR_CODES, REALTIME_HOOKS_TOKEN, REALTIME_INSTANCE_ID_TOKEN, REALTIME_LOG_EVENTS, REALTIME_OFFLINE_QUEUE_TOKEN, REALTIME_OPTIONS_TOKEN, REALTIME_PRESENCE_TOKEN, REALTIME_PUBSUB_TOKEN, REALTIME_TRANSPORT_TOKEN, REFUSAL_REASONS, RESERVED_EVENT_NAMES, ROOM_PREFIXES, RealtimeMetricsTally, RealtimePubSubSubscriber, RealtimeService, RealtimeTracing, ReauthenticationService, RedisOfflineQueue, RedisRealtimePubSub, RoomRegistry, SseSubscriptionHandler, SseTransport, TALLY_TRANSPORTS, UNBOUNDED_TICKET, admitRooms, assertIdentityIsNotBlank, composeForRoot, composeForRootAsync, composeRoomId, createSseController, describeError, logEvent, parseCookieHeader, quitWithin, realtimeError, refuseReservedRoom, reportDeliveryFailure, requireRoomName, resolveAuthTenant, runHook, sseWiring, unavailableError };