@bymax-one/nest-realtime 1.2.18 → 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,16 @@ 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
+
44
54
  // src/server/config/drop-unset.ts
45
55
  var SSE_KEYS = {
46
56
  endpoint: true,
@@ -105,8 +115,7 @@ function dropUnset(options) {
105
115
  const kept = readSet(options, TOP_LEVEL_KEYS);
106
116
  for (const [group, keys] of Object.entries(GROUPS)) {
107
117
  const value = kept[group];
108
- if (typeof value === "object" && !Array.isArray(value))
109
- kept[group] = readSet(value, keys);
118
+ if (isPlainObject(value)) kept[group] = readSet(value, keys);
110
119
  }
111
120
  return kept;
112
121
  }
@@ -160,7 +169,9 @@ function describeReceived(value) {
160
169
  return Number.isFinite(value) ? String(value) : "a number that is not finite";
161
170
  }
162
171
  if (value === null) return "null";
163
- return Array.isArray(value) ? "an array" : KIND_OF_TYPE[typeof value] ?? "an object";
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";
164
175
  }
165
176
 
166
177
  // src/server/utils/realtime-error.ts
@@ -171,6 +182,15 @@ function realtimeError(code, detail, options = {}) {
171
182
  return Object.assign(error, { code });
172
183
  }
173
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
+
174
194
  // src/server/config/validate-shapes.ts
175
195
  var REQUIRED_FUNCTIONS = {
176
196
  pubsub: ["publish", "subscribe"],
@@ -192,11 +212,8 @@ function refuse(path, expected, received) {
192
212
  { who: "BymaxRealtimeModule" }
193
213
  );
194
214
  }
195
- function isObject(value) {
196
- return typeof value === "object" && value !== null && !Array.isArray(value);
197
- }
198
215
  function assertObject(path, value) {
199
- if (value !== void 0 && !isObject(value)) refuse(path, "an object", value);
216
+ if (value !== void 0 && !isPlainObject(value)) refuse(path, "an object", value);
200
217
  }
201
218
  function assertFunction(path, value) {
202
219
  if (typeof value !== "function") refuse(path, "a function", value);
@@ -207,10 +224,15 @@ function assertOptionalFunction(path, value) {
207
224
  function assertBoolean(path, value) {
208
225
  if (value !== void 0 && typeof value !== "boolean") refuse(path, "a boolean", value);
209
226
  }
210
- function assertEndpoint(path, value) {
211
- if (value !== void 0 && !(typeof value === "string" && value.trim().length > 0)) {
227
+ function assertSseEndpoint(path, value) {
228
+ if (value === void 0 || value === null) return;
229
+ if (typeof value !== "string" || value.trim().length === 0) {
212
230
  refuse(path, "a non-blank string", value);
213
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);
214
236
  }
215
237
  function validatePieces(options) {
216
238
  for (const [name, functions] of Object.entries(REQUIRED_FUNCTIONS)) {
@@ -235,12 +257,13 @@ function validateShapes(options) {
235
257
  assertOptionalFunction("tenantResolver", options.tenantResolver);
236
258
  assertBoolean("sse.emitConnectionEvent", options.sse?.emitConnectionEvent);
237
259
  assertBoolean("websocket.emitConnectionEvent", options.websocket?.emitConnectionEvent);
238
- assertEndpoint("sse.endpoint", options.sse?.endpoint);
260
+ assertSseEndpoint("sse.endpoint", options.sse?.endpoint);
239
261
  }
240
262
 
241
263
  // src/server/config/validate-options.ts
242
264
  var VALID_TRANSPORTS = /* @__PURE__ */ new Set(["sse", "websocket", "both"]);
243
265
  function validateOptions(raw) {
266
+ assertOptionsObject(raw);
244
267
  const options = dropUnset(raw);
245
268
  if (!options.transport || !VALID_TRANSPORTS.has(options.transport)) {
246
269
  throw realtimeError(
@@ -331,12 +354,6 @@ function validateReauthPolicy(options) {
331
354
  { who: "BymaxRealtimeModule" }
332
355
  );
333
356
  }
334
- if (policy?.cacheTtlMs !== void 0 && policy.intervalSeconds !== void 0 && policy.cacheTtlMs > policy.intervalSeconds * 1e3) {
335
- Logger.warn(
336
- `[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`,
337
- "BymaxRealtimeModule"
338
- );
339
- }
340
357
  }
341
358
  function validateSseOptions(options) {
342
359
  const sse = options.sse;
@@ -368,6 +385,138 @@ function validateSseOptions(options) {
368
385
  MAX_PER_USER_CONNECTIONS
369
386
  );
370
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
+ }
371
520
 
372
521
  // src/server/utils/describe-error.ts
373
522
  function describeError(reason) {
@@ -381,13 +530,32 @@ function describeError(reason) {
381
530
 
382
531
  // src/server/utils/report-delivery-failure.ts
383
532
  function reportDeliveryFailure(logger, hooks, failure, what) {
384
- 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
+ );
385
544
  const reported = {
386
545
  ...failure,
387
546
  error: failure.error instanceof Error ? failure.error : new Error(describeError(failure.error))
388
547
  };
389
548
  void Promise.resolve().then(() => hooks?.onDeliveryFailure?.(reported)).catch((err) => {
390
- 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
+ );
391
559
  });
392
560
  }
393
561
 
@@ -432,8 +600,12 @@ var OfflineQueueDeliveryService = class {
432
600
  timeouts = windowedReport(
433
601
  () => 0,
434
602
  (count) => {
435
- this.logger.warn(
436
- `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 }
437
609
  );
438
610
  }
439
611
  );
@@ -462,8 +634,12 @@ var OfflineQueueDeliveryService = class {
462
634
  return { events: [], degraded: true };
463
635
  }
464
636
  if (events.length === RETRIEVE_LIMIT) {
465
- this.logger.warn(
466
- `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 }
467
643
  );
468
644
  }
469
645
  return { events, degraded: false };
@@ -474,7 +650,14 @@ var OfflineQueueDeliveryService = class {
474
650
  try {
475
651
  await this.storage.acknowledge(userId, lastId);
476
652
  } catch (err) {
477
- 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
+ );
478
661
  }
479
662
  }
480
663
  async retrieveAppended(userId, lastEventId, read) {
@@ -680,6 +863,7 @@ var AuthenticationUnavailableError = class extends Error {
680
863
  this.reason = reason;
681
864
  }
682
865
  reason;
866
+ code = REALTIME_ERROR_CODES.TRANSPORT_UNAVAILABLE;
683
867
  };
684
868
  var AuthenticationGate = class {
685
869
  constructor(options, authenticator) {
@@ -695,8 +879,17 @@ var AuthenticationGate = class {
695
879
  refusals = windowedReport(
696
880
  () => ({ saturated: 0, timeout: 0 }),
697
881
  ({ saturated, timeout }) => {
698
- this.logger.warn(
699
- `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
+ }
700
893
  );
701
894
  }
702
895
  );
@@ -812,6 +1005,7 @@ var ConnectionLimitError = class extends Error {
812
1005
  this.limit = limit;
813
1006
  }
814
1007
  limit;
1008
+ code = REALTIME_ERROR_CODES.TRANSPORT_UNAVAILABLE;
815
1009
  };
816
1010
  var UNBOUNDED_TICKET = {
817
1011
  release: () => void 0,
@@ -831,8 +1025,12 @@ var ConnectionAdmission = class {
831
1025
  refusals = windowedReport(
832
1026
  () => 0,
833
1027
  (count) => {
834
- this.logger.warn(
835
- `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 }
836
1034
  );
837
1035
  }
838
1036
  );
@@ -1216,7 +1414,7 @@ var StallWatch = class {
1216
1414
  // src/server/transports/sse/sse.transport.ts
1217
1415
  var _shuttingDown;
1218
1416
  var SseTransport = class {
1219
- 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) {
1220
1418
  this.connections = connections;
1221
1419
  this.rooms = rooms;
1222
1420
  this.replayBuffer = replayBuffer;
@@ -1229,6 +1427,7 @@ var SseTransport = class {
1229
1427
  this.instanceId = instanceId;
1230
1428
  this.offlineQueue = offlineQueue;
1231
1429
  this.admission = admission;
1430
+ this.tally = tally;
1232
1431
  __publicField(this, "kind", "sse");
1233
1432
  __publicField(this, "logger", new Logger(SseTransport.name));
1234
1433
  __privateAdd(this, _shuttingDown, false);
@@ -1246,6 +1445,7 @@ var SseTransport = class {
1246
1445
  instanceId;
1247
1446
  offlineQueue;
1248
1447
  admission;
1448
+ tally;
1249
1449
  onModuleDestroy() {
1250
1450
  __privateSet(this, _shuttingDown, true);
1251
1451
  }
@@ -1332,7 +1532,18 @@ var SseTransport = class {
1332
1532
  }),
1333
1533
  this.options.hookTimeoutMs ?? DEFAULT_HOOK_TIMEOUT_MS
1334
1534
  );
1335
- 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
+ }
1336
1547
  }
1337
1548
  getReplayEvents(userId, lastEventId) {
1338
1549
  return this.replayBuffer.since(userId, lastEventId);
@@ -1434,15 +1645,18 @@ var SseTransport = class {
1434
1645
  }
1435
1646
  emitToUserLocal(userId, event, data, id) {
1436
1647
  const message = this.buildMessage(id, event, data);
1648
+ this.tally?.emitted("sse");
1437
1649
  this.replayBuffer.append(userId, message);
1438
1650
  for (const conn of this.connections.byUser(userId, "sse")) this.deliver(conn, message);
1439
1651
  }
1440
1652
  emitToTenantLocal(tenantId, event, data, id) {
1441
1653
  const message = this.buildMessage(id, event, data);
1654
+ this.tally?.emitted("sse");
1442
1655
  for (const conn of this.connections.byTenant(tenantId, "sse")) this.deliver(conn, message);
1443
1656
  }
1444
1657
  emitToRoomLocal(roomId, event, data, id) {
1445
1658
  const message = this.buildMessage(id, event, data);
1659
+ this.tally?.emitted("sse");
1446
1660
  for (const connectionId of this.rooms.members(roomId)) {
1447
1661
  const conn = this.connections.get(connectionId);
1448
1662
  if (conn && conn.transport === "sse") this.deliver(conn, message);
@@ -1450,6 +1664,7 @@ var SseTransport = class {
1450
1664
  }
1451
1665
  broadcastLocal(event, data, id) {
1452
1666
  const message = this.buildMessage(id, event, data);
1667
+ this.tally?.emitted("sse");
1453
1668
  for (const conn of this.connections.allByTransport("sse")) this.deliver(conn, message);
1454
1669
  }
1455
1670
  async disconnectLocal(connectionId, reason) {
@@ -1472,7 +1687,16 @@ var SseTransport = class {
1472
1687
  }
1473
1688
  conn.subject?.next(message);
1474
1689
  } catch (error) {
1475
- 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
+ );
1476
1700
  }
1477
1701
  }
1478
1702
  track(params) {
@@ -1499,13 +1723,23 @@ var SseTransport = class {
1499
1723
  }
1500
1724
  }
1501
1725
  cutSlowConsumer(connectionId, why, tracked) {
1502
- this.logger.warn(
1503
- `${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)`
1504
- );
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
+ });
1505
1734
  this.disconnectLocal(connectionId, REALTIME_ERROR_CODES.SLOW_CONSUMER).catch(
1506
1735
  (error) => {
1507
- this.logger.warn(
1508
- `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
1509
1743
  );
1510
1744
  }
1511
1745
  );
@@ -1536,6 +1770,7 @@ var SseTransport = class {
1536
1770
  let userConnections = this.connections.byUser(userId, "sse");
1537
1771
  while (userConnections.length > max) {
1538
1772
  const oldest = userConnections.reduce((a, b) => a.connectedAt <= b.connectedAt ? a : b);
1773
+ this.tally?.evicted("per_user_cap");
1539
1774
  await this.disconnectLocal(oldest.connectionId, REALTIME_ERROR_CODES.TOO_MANY_CONNECTIONS);
1540
1775
  userConnections = this.connections.byUser(userId, "sse");
1541
1776
  }
@@ -1557,7 +1792,9 @@ SseTransport = __decorateClass([
1557
1792
  __decorateParam(10, Optional()),
1558
1793
  __decorateParam(10, Inject(REALTIME_OFFLINE_QUEUE_TOKEN)),
1559
1794
  __decorateParam(11, Optional()),
1560
- __decorateParam(11, Inject(ConnectionAdmission))
1795
+ __decorateParam(11, Inject(ConnectionAdmission)),
1796
+ __decorateParam(12, Optional()),
1797
+ __decorateParam(12, Inject(RealtimeMetricsTally))
1561
1798
  ], SseTransport);
1562
1799
 
1563
1800
  // src/server/transports/sse/response-close.ts
@@ -1631,18 +1868,22 @@ function buildMeta(record) {
1631
1868
  };
1632
1869
  }
1633
1870
  var SseSubscriptionHandler = class {
1634
- constructor(transport, heartbeat, options, hooks, offlineDelivery) {
1871
+ constructor(transport, heartbeat, options, hooks, offlineDelivery, tally, tracing) {
1635
1872
  this.transport = transport;
1636
1873
  this.heartbeat = heartbeat;
1637
1874
  this.options = options;
1638
1875
  this.hooks = hooks;
1639
1876
  this.offlineDelivery = offlineDelivery;
1877
+ this.tally = tally;
1878
+ this.tracing = tracing;
1640
1879
  }
1641
1880
  transport;
1642
1881
  heartbeat;
1643
1882
  options;
1644
1883
  hooks;
1645
1884
  offlineDelivery;
1885
+ tally;
1886
+ tracing;
1646
1887
  logger = new Logger(SseSubscriptionHandler.name);
1647
1888
  authenticated = /* @__PURE__ */ new WeakMap();
1648
1889
  resolveAndValidateIdentity(auth) {
@@ -1651,7 +1892,15 @@ var SseSubscriptionHandler = class {
1651
1892
  assertIdentityIsNotBlank(resolvedAuth);
1652
1893
  resolvedAuth = admitRooms(resolvedAuth);
1653
1894
  } catch (err) {
1654
- 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
+ );
1655
1904
  throw new InternalServerErrorException();
1656
1905
  }
1657
1906
  return resolvedAuth;
@@ -1686,6 +1935,7 @@ var SseSubscriptionHandler = class {
1686
1935
  }
1687
1936
  refuseDuringShutdown() {
1688
1937
  if (this.transport.shuttingDown) {
1938
+ this.tally?.refused("unavailable");
1689
1939
  throw new ServiceUnavailableException(REALTIME_ERROR_CODES.TRANSPORT_UNAVAILABLE);
1690
1940
  }
1691
1941
  }
@@ -1723,16 +1973,29 @@ var SseSubscriptionHandler = class {
1723
1973
  }
1724
1974
  }
1725
1975
  toClientError(err, what) {
1726
- if (err instanceof AuthenticationUnavailableError || err instanceof ConnectionLimitError) {
1976
+ if (err instanceof ConnectionLimitError) {
1977
+ this.tally?.refused("limit");
1978
+ return new ServiceUnavailableException();
1979
+ }
1980
+ if (err instanceof AuthenticationUnavailableError) {
1981
+ this.tally?.refused("unavailable");
1727
1982
  return new ServiceUnavailableException();
1728
1983
  }
1984
+ if (err instanceof HttpException && err.getStatus() === HttpStatus.UNAUTHORIZED) {
1985
+ this.tally?.refused("unauthorized");
1986
+ }
1729
1987
  return err instanceof HttpException ? err : this.serverError(err, what);
1730
1988
  }
1731
1989
  serverError(err, what) {
1732
- 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);
1733
1992
  return new InternalServerErrorException();
1734
1993
  }
1735
- 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) {
1736
1999
  const held = this.transport.admit();
1737
2000
  const detach = onResponseClose(res, () => ticket.release());
1738
2001
  const ticket = {
@@ -1866,7 +2129,14 @@ var SseSubscriptionHandler = class {
1866
2129
  fireHook(invoke, onFailure) {
1867
2130
  void runHook(invoke).then((failed) => {
1868
2131
  if (!failed) return;
1869
- 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
+ );
1870
2140
  onFailure?.();
1871
2141
  });
1872
2142
  }
@@ -1879,7 +2149,11 @@ SseSubscriptionHandler = __decorateClass([
1879
2149
  __decorateParam(3, Optional()),
1880
2150
  __decorateParam(3, Inject(REALTIME_HOOKS_TOKEN)),
1881
2151
  __decorateParam(4, Optional()),
1882
- __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))
1883
2157
  ], SseSubscriptionHandler);
1884
2158
 
1885
2159
  // src/server/utils/normalize-endpoint-path.ts
@@ -1930,12 +2204,14 @@ function createSseController(endpoint) {
1930
2204
  return DynamicSseController;
1931
2205
  }
1932
2206
  var RealtimeService = class {
1933
- constructor(transport, pubsub) {
2207
+ constructor(transport, pubsub, tally) {
1934
2208
  this.transport = transport;
1935
2209
  this.pubsub = pubsub;
2210
+ this.tally = tally;
1936
2211
  }
1937
2212
  transport;
1938
2213
  pubsub;
2214
+ tally;
1939
2215
  isPubSubReady() {
1940
2216
  if (this.transport.kind === "websocket") return true;
1941
2217
  return this.pubsub?.isSubscribed?.() ?? true;
@@ -1961,15 +2237,18 @@ var RealtimeService = class {
1961
2237
  refuseReservedRoom("leaveRoom", roomId);
1962
2238
  return this.transport.leaveRoom(connectionId, roomId);
1963
2239
  }
1964
- disconnect(connectionId, reason) {
1965
- return this.transport.disconnect(connectionId, reason);
2240
+ async disconnect(connectionId, reason) {
2241
+ await this.transport.disconnect(connectionId, reason);
2242
+ this.tally?.evicted("revoked");
1966
2243
  }
1967
2244
  };
1968
2245
  RealtimeService = __decorateClass([
1969
2246
  Injectable(),
1970
2247
  __decorateParam(0, Inject(REALTIME_TRANSPORT_TOKEN)),
1971
2248
  __decorateParam(1, Optional()),
1972
- __decorateParam(1, Inject(REALTIME_PUBSUB_TOKEN))
2249
+ __decorateParam(1, Inject(REALTIME_PUBSUB_TOKEN)),
2250
+ __decorateParam(2, Optional()),
2251
+ __decorateParam(2, Inject(RealtimeMetricsTally))
1973
2252
  ], RealtimeService);
1974
2253
 
1975
2254
  // src/server/utils/semaphore.ts
@@ -2003,31 +2282,55 @@ function resolvePolicy(raw) {
2003
2282
  };
2004
2283
  }
2005
2284
  var ReauthenticationService = class {
2006
- constructor(connections, realtime, auth, options, hooks) {
2285
+ constructor(connections, realtime, auth, options, hooks, tracing) {
2007
2286
  this.connections = connections;
2008
2287
  this.realtime = realtime;
2009
2288
  this.auth = auth;
2010
2289
  this.hooks = hooks;
2290
+ this.tracing = tracing;
2011
2291
  this.policy = resolvePolicy(options.reauthenticationPolicy);
2292
+ this.declared = options.reauthenticationPolicy;
2012
2293
  this.slots = new Semaphore(this.policy.concurrency);
2013
2294
  }
2014
2295
  connections;
2015
2296
  realtime;
2016
2297
  auth;
2017
2298
  hooks;
2299
+ tracing;
2018
2300
  logger = new Logger(ReauthenticationService.name);
2019
2301
  timer = null;
2020
2302
  policy;
2303
+ declared;
2021
2304
  inFlight = /* @__PURE__ */ new Set();
2022
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
+ }
2023
2318
  onModuleInit() {
2024
2319
  if (!this.auth.revalidate) {
2025
2320
  this.logger.log("Authenticator does not implement revalidate() \u2014 reauthentication disabled");
2026
2321
  return;
2027
2322
  }
2323
+ this.warnIfCacheOutlivesInterval();
2028
2324
  this.timer = setInterval(() => {
2029
2325
  this.runCycle().catch((err) => {
2030
- 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
+ );
2031
2334
  });
2032
2335
  }, this.policy.intervalSeconds * 1e3);
2033
2336
  this.timer.unref();
@@ -2045,7 +2348,10 @@ var ReauthenticationService = class {
2045
2348
  ...this.connections.allByTransport("sse"),
2046
2349
  ...this.connections.allByTransport("websocket")
2047
2350
  ];
2048
- 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());
2049
2355
  }
2050
2356
  async check(conn, now) {
2051
2357
  if (this.inFlight.has(conn.connectionId)) return;
@@ -2082,7 +2388,14 @@ var ReauthenticationService = class {
2082
2388
  }
2083
2389
  await this.revoke(conn);
2084
2390
  } catch (err) {
2085
- 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
+ );
2086
2399
  await this.revoke(conn);
2087
2400
  }
2088
2401
  }
@@ -2106,8 +2419,13 @@ var ReauthenticationService = class {
2106
2419
  try {
2107
2420
  await this.bounded("revocation", () => this.handleFailure(conn));
2108
2421
  } catch (err) {
2109
- this.logger.warn(
2110
- `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
2111
2429
  );
2112
2430
  }
2113
2431
  }
@@ -2128,15 +2446,27 @@ var ReauthenticationService = class {
2128
2446
  })
2129
2447
  ).then((failed) => {
2130
2448
  if (failed) {
2131
- 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
+ );
2132
2457
  }
2133
2458
  });
2134
2459
  await this.realtime.disconnect(conn.connectionId, REALTIME_ERROR_CODES.REAUTHENTICATION_FAILED);
2135
2460
  }
2136
2461
  notify(conn) {
2137
2462
  const failed = (err) => {
2138
- this.logger.warn(
2139
- `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
2140
2470
  );
2141
2471
  };
2142
2472
  try {
@@ -2155,7 +2485,9 @@ ReauthenticationService = __decorateClass([
2155
2485
  __decorateParam(2, Inject(REALTIME_AUTHENTICATOR_TOKEN)),
2156
2486
  __decorateParam(3, Inject(REALTIME_OPTIONS_TOKEN)),
2157
2487
  __decorateParam(4, Optional()),
2158
- __decorateParam(4, Inject(REALTIME_HOOKS_TOKEN))
2488
+ __decorateParam(4, Inject(REALTIME_HOOKS_TOKEN)),
2489
+ __decorateParam(5, Optional()),
2490
+ __decorateParam(5, Inject(RealtimeTracing))
2159
2491
  ], ReauthenticationService);
2160
2492
 
2161
2493
  // src/server/composition/realtime-module.factory.ts
@@ -2163,6 +2495,7 @@ var DEFAULT_ASYNC_SSE_ENDPOINT = "/events";
2163
2495
  var EXPORTED_TOKENS = [
2164
2496
  RealtimeService,
2165
2497
  ConnectionRegistry,
2498
+ RealtimeMetricsTally,
2166
2499
  REALTIME_OPTIONS_TOKEN,
2167
2500
  REALTIME_INSTANCE_ID_TOKEN,
2168
2501
  REALTIME_AUTHENTICATOR_TOKEN,
@@ -2182,7 +2515,9 @@ var SHARED_SERVICES = [
2182
2515
  ReauthenticationService,
2183
2516
  OfflineQueueDeliveryService,
2184
2517
  AuthenticationGate,
2185
- ConnectionAdmission
2518
+ ConnectionAdmission,
2519
+ RealtimeMetricsTally,
2520
+ RealtimeTracing
2186
2521
  ];
2187
2522
  function assertModeSupported(wiring, mode, moduleName) {
2188
2523
  if (wiring.modes.includes(mode)) return;
@@ -2196,7 +2531,10 @@ function assertModeSupported(wiring, mode, moduleName) {
2196
2531
  function warnIfSingleInstance(pubsub, transport, logger) {
2197
2532
  if (transport === "websocket") return;
2198
2533
  if (!pubsub && process.env["NODE_ENV"] === "production") {
2199
- logger.warn(
2534
+ logEvent(
2535
+ logger,
2536
+ "warn",
2537
+ "REALTIME_PUBSUB_NOT_PROVIDED",
2200
2538
  "No IRealtimePubSub provided in production \u2014 single-instance only. Provide a Redis-backed IRealtimePubSub for horizontal scaling."
2201
2539
  );
2202
2540
  }
@@ -2214,6 +2552,7 @@ function buildCommonProviders(resolved, instanceId) {
2214
2552
  ];
2215
2553
  }
2216
2554
  function composeForRoot(moduleClass, wiring, logger, raw) {
2555
+ assertOptionsObject(raw, moduleClass.name);
2217
2556
  const options = dropUnset(raw);
2218
2557
  validateOptions(options);
2219
2558
  assertModeSupported(wiring, options.transport, moduleClass.name);
@@ -2248,9 +2587,10 @@ function bindSseEndpoint(resolved, declared, bound, moduleName) {
2248
2587
  return Object.freeze({ ...resolved, sse: { ...resolved.sse, endpoint: bound } });
2249
2588
  }
2250
2589
  function resolveAsyncOptions(raw, declaredMode, instanceId, source, logger, moduleName) {
2251
- if (!raw) {
2590
+ if (raw === void 0 || raw === null) {
2252
2591
  throw realtimeError(REALTIME_ERROR_CODES.INVALID_OPTIONS, `${source} returned nothing`);
2253
2592
  }
2593
+ assertOptionsObject(raw, moduleName);
2254
2594
  const options = dropUnset(raw);
2255
2595
  validateOptions(options);
2256
2596
  if (options.transport !== declaredMode) {
@@ -2264,12 +2604,15 @@ function resolveAsyncOptions(raw, declaredMode, instanceId, source, logger, modu
2264
2604
  logger.log(`Bootstrapped (transport=${resolved.transport}, instanceId=${instanceId})`);
2265
2605
  return { resolved, declaredEndpoint: options.sse?.endpoint };
2266
2606
  }
2607
+ function isSet(pattern) {
2608
+ return pattern !== void 0 && pattern !== null;
2609
+ }
2267
2610
  function assertOneFactoryPattern(asyncOptions, moduleName) {
2268
2611
  const patterns = [
2269
2612
  asyncOptions.useFactory,
2270
2613
  asyncOptions.useClass,
2271
2614
  asyncOptions.useExisting
2272
- ].filter((pattern) => pattern !== void 0);
2615
+ ].filter(isSet);
2273
2616
  if (patterns.length === 1) return;
2274
2617
  throw realtimeError(
2275
2618
  REALTIME_ERROR_CODES.INVALID_OPTIONS,
@@ -2278,7 +2621,7 @@ function assertOneFactoryPattern(asyncOptions, moduleName) {
2278
2621
  );
2279
2622
  }
2280
2623
  function buildOptionsProvider(asyncOptions, resolve, factoryToken) {
2281
- if (asyncOptions.useFactory) {
2624
+ if (isSet(asyncOptions.useFactory)) {
2282
2625
  return {
2283
2626
  provide: REALTIME_OPTIONS_TOKEN,
2284
2627
  useFactory: async (...args) => resolve(await asyncOptions.useFactory(...args), "useFactory"),
@@ -2287,10 +2630,18 @@ function buildOptionsProvider(asyncOptions, resolve, factoryToken) {
2287
2630
  }
2288
2631
  return {
2289
2632
  provide: REALTIME_OPTIONS_TOKEN,
2290
- useFactory: async (factory) => resolve(
2291
- await factory.createRealtimeOptions(),
2292
- "createRealtimeOptions"
2293
- ),
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
+ },
2294
2645
  inject: [asyncOptions.useExisting ?? factoryToken]
2295
2646
  };
2296
2647
  }
@@ -2326,14 +2677,16 @@ function buildResolver(asyncOptions, instanceId, boundSseEndpoint, logger, modul
2326
2677
  }
2327
2678
  function composeForRootAsync(moduleClass, wiring, logger, asyncOptions) {
2328
2679
  const moduleName = moduleClass.name;
2680
+ assertOptionsObject(asyncOptions, moduleName);
2329
2681
  assertOneFactoryPattern(asyncOptions, moduleName);
2330
2682
  assertModeSupported(wiring, asyncOptions.transport, moduleName);
2683
+ assertSseEndpoint("sseEndpoint", asyncOptions.sseEndpoint);
2331
2684
  assertSseEndpointApplies(asyncOptions, moduleName);
2332
2685
  const FACTORY_TOKEN = /* @__PURE__ */ Symbol("REALTIME_OPTIONS_FACTORY");
2333
2686
  const instanceId = randomUUID();
2334
2687
  const boundSseEndpoint = asyncOptions.sseEndpoint ?? DEFAULT_ASYNC_SSE_ENDPOINT;
2335
2688
  const resolve = buildResolver(asyncOptions, instanceId, boundSseEndpoint, logger, moduleName);
2336
- const factoryClassProvider = asyncOptions.useClass ? [{ provide: FACTORY_TOKEN, useClass: asyncOptions.useClass }] : [];
2689
+ const factoryClassProvider = isSet(asyncOptions.useClass) ? [{ provide: FACTORY_TOKEN, useClass: asyncOptions.useClass }] : [];
2337
2690
  const { providers: transportProviders, controllers } = wiring.buildAsync({
2338
2691
  mode: asyncOptions.transport,
2339
2692
  sseEndpoint: boundSseEndpoint
@@ -2372,7 +2725,14 @@ var RealtimePubSubSubscriber = class {
2372
2725
  try {
2373
2726
  await this.unsubscribe();
2374
2727
  } catch (err) {
2375
- 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
+ );
2376
2736
  }
2377
2737
  this.unsubscribe = null;
2378
2738
  }
@@ -2380,8 +2740,12 @@ var RealtimePubSubSubscriber = class {
2380
2740
  dropped = windowedReport(
2381
2741
  () => ({ count: 0, last: "none" }),
2382
2742
  ({ count, last }) => {
2383
- this.logger.warn(
2384
- `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 }
2385
2749
  );
2386
2750
  }
2387
2751
  );
@@ -2409,17 +2773,9 @@ var RealtimePubSubSubscriber = class {
2409
2773
  this.sse.broadcastLocal(a.event, a.data, a.id);
2410
2774
  break;
2411
2775
  }
2412
- case "disconnect": {
2413
- const a = msg.args;
2414
- Promise.resolve(this.sse.disconnectLocal(a.connectionId, a.reason)).catch(
2415
- (err) => {
2416
- this.logger.warn(
2417
- `Remote disconnect of ${a.connectionId} failed: ${describeError(err)}`
2418
- );
2419
- }
2420
- );
2776
+ case "disconnect":
2777
+ this.closeLocal(msg.args);
2421
2778
  break;
2422
- }
2423
2779
  default: {
2424
2780
  msg.op;
2425
2781
  this.drop("unknown op");
@@ -2429,6 +2785,18 @@ var RealtimePubSubSubscriber = class {
2429
2785
  this.drop(String(Object(err).constructor?.name ?? "Error"));
2430
2786
  }
2431
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
+ }
2432
2800
  drop(last) {
2433
2801
  this.dropped(({ count }) => ({ count: count + 1, last }));
2434
2802
  }
@@ -2522,11 +2890,6 @@ var CANNOT_PUBLISH = /* @__PURE__ */ new Set([
2522
2890
  var PUBLISHER_WAIT_MS = 2e3;
2523
2891
  var PUBLISH_WAIT_MS = 2e3;
2524
2892
  var CONNECTION_OVER = ["ready", "close", "reconnecting", "end"];
2525
- function connectionReason(err) {
2526
- const code = err?.code;
2527
- const text = describeError(err);
2528
- return [typeof code === "string" ? code : "", text].filter(Boolean).join(" ") || String(err);
2529
- }
2530
2893
  var RedisRealtimePubSub = class _RedisRealtimePubSub {
2531
2894
  #pub;
2532
2895
  channel;
@@ -2664,7 +3027,7 @@ var RedisRealtimePubSub = class _RedisRealtimePubSub {
2664
3027
  if (outcome === "subscribed") {
2665
3028
  this.markUp();
2666
3029
  } else {
2667
- this.markDown(connectionReason(outcome.unreachable));
3030
+ this.markDown(void 0, outcome.unreachable);
2668
3031
  first.catch((err) => this.refused(err));
2669
3032
  }
2670
3033
  } catch (err) {
@@ -2690,8 +3053,13 @@ var RedisRealtimePubSub = class _RedisRealtimePubSub {
2690
3053
  const reason = describeError(err);
2691
3054
  if (reason === this.#lastRefusal) return;
2692
3055
  this.#lastRefusal = reason;
2693
- this.logger.warn(
2694
- `${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
2695
3063
  );
2696
3064
  }
2697
3065
  markUp() {
@@ -2703,20 +3071,29 @@ var RedisRealtimePubSub = class _RedisRealtimePubSub {
2703
3071
  `Subscribed to "${this.channel}"; remote events and revocations reach this instance`
2704
3072
  );
2705
3073
  }
2706
- markDown(reason) {
3074
+ markDown(wording, error) {
2707
3075
  this.#subscribed = false;
2708
3076
  if (this.#outageLogged) return;
2709
3077
  this.#outageLogged = true;
2710
- this.logger.warn(
2711
- `${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
2712
3085
  );
2713
3086
  }
2714
3087
  reportMalformed() {
2715
3088
  this.malformedDropped++;
2716
3089
  const now = Date.now();
2717
3090
  if (now - this.malformedReportedAt < MALFORMED_REPORT_INTERVAL_MS) return;
2718
- this.logger.warn(
2719
- `${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" }
2720
3097
  );
2721
3098
  this.malformedDropped = 0;
2722
3099
  this.malformedReportedAt = now;
@@ -2763,6 +3140,10 @@ var RedisOfflineQueue = class _RedisOfflineQueue {
2763
3140
  static MS_PAD = 16;
2764
3141
  static COUNTER_PAD = 6;
2765
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
+ }
2766
3147
  this.#client = options.client;
2767
3148
  this.maxPerUser = requireInteger(
2768
3149
  "maxPerUser",
@@ -2828,4 +3209,4 @@ var RedisOfflineQueue = class _RedisOfflineQueue {
2828
3209
  }
2829
3210
  };
2830
3211
 
2831
- 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 };