@bymax-one/nest-realtime 1.2.5 → 1.2.7

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.
@@ -4,6 +4,7 @@ var crypto = require('crypto');
4
4
  var common = require('@nestjs/common');
5
5
  var rxjs = require('rxjs');
6
6
  var operators = require('rxjs/operators');
7
+ var net = require('net');
7
8
 
8
9
  var __defProp = Object.defineProperty;
9
10
  var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
@@ -28,6 +29,7 @@ var REALTIME_ERROR_CODES = {
28
29
  TOO_MANY_CONNECTIONS: "REALTIME_TOO_MANY_CONNECTIONS",
29
30
  INVALID_TICKET: "REALTIME_INVALID_TICKET",
30
31
  PUBSUB_UNAVAILABLE: "REALTIME_PUBSUB_UNAVAILABLE",
32
+ TRANSPORT_UNAVAILABLE: "REALTIME_TRANSPORT_UNAVAILABLE",
31
33
  REDIS_ADAPTER_FAILED: "REALTIME_REDIS_ADAPTER_FAILED",
32
34
  PAYLOAD_TOO_LARGE: "REALTIME_PAYLOAD_TOO_LARGE",
33
35
  REPLAY_BUFFER_MISS: "REALTIME_REPLAY_BUFFER_MISS"
@@ -116,13 +118,27 @@ function describeError(reason) {
116
118
  }
117
119
  }
118
120
 
121
+ // src/server/utils/report-delivery-failure.ts
122
+ function reportDeliveryFailure(logger, hooks, failure, what) {
123
+ logger.warn(`${failure.code} op=${failure.op}: ${what}: ${describeError(failure.error)}`);
124
+ const reported = {
125
+ ...failure,
126
+ error: failure.error instanceof Error ? failure.error : new Error(describeError(failure.error))
127
+ };
128
+ void Promise.resolve().then(() => hooks?.onDeliveryFailure?.(reported)).catch((err) => {
129
+ logger.warn(`onDeliveryFailure hook failed: ${describeError(err)}`);
130
+ });
131
+ }
132
+
119
133
  // src/server/offline-queue/offline-queue-delivery.service.ts
120
134
  var RETRIEVE_LIMIT = 200;
121
135
  exports.OfflineQueueDeliveryService = class OfflineQueueDeliveryService {
122
- constructor(storage) {
136
+ constructor(storage, hooks) {
123
137
  this.storage = storage;
138
+ this.hooks = hooks;
124
139
  }
125
140
  storage;
141
+ hooks;
126
142
  logger = new common.Logger(exports.OfflineQueueDeliveryService.name);
127
143
  /**
128
144
  * Return events for `userId` that arrived after `lastEventId` and are NOT
@@ -143,7 +159,16 @@ exports.OfflineQueueDeliveryService = class OfflineQueueDeliveryService {
143
159
  try {
144
160
  events = await this.storage.retrieveSince(userId, lastEventId, RETRIEVE_LIMIT);
145
161
  } catch (err) {
146
- this.logger.warn(`Offline queue retrieve failed: ${describeError(err)}`);
162
+ reportDeliveryFailure(
163
+ this.logger,
164
+ this.hooks,
165
+ {
166
+ code: REALTIME_ERROR_CODES.TRANSPORT_UNAVAILABLE,
167
+ op: "offlineRetrieve",
168
+ error: err
169
+ },
170
+ "Offline queue retrieve failed"
171
+ );
147
172
  return [];
148
173
  }
149
174
  if (events.length === RETRIEVE_LIMIT) {
@@ -177,7 +202,9 @@ exports.OfflineQueueDeliveryService = class OfflineQueueDeliveryService {
177
202
  exports.OfflineQueueDeliveryService = __decorateClass([
178
203
  common.Injectable(),
179
204
  __decorateParam(0, common.Optional()),
180
- __decorateParam(0, common.Inject(REALTIME_OFFLINE_QUEUE_TOKEN))
205
+ __decorateParam(0, common.Inject(REALTIME_OFFLINE_QUEUE_TOKEN)),
206
+ __decorateParam(1, common.Optional()),
207
+ __decorateParam(1, common.Inject(REALTIME_HOOKS_TOKEN))
181
208
  ], exports.OfflineQueueDeliveryService);
182
209
 
183
210
  // src/shared/constants/reserved-events.constants.ts
@@ -228,6 +255,25 @@ function parseCookieHeader(cookieHeader) {
228
255
  }
229
256
  return out;
230
257
  }
258
+ var IPV6 = 6;
259
+ function isHeaderAddress(candidate) {
260
+ return typeof candidate === "string" && !candidate.includes("%") && net.isIP(candidate) !== 0;
261
+ }
262
+ function peerAddress(remoteAddress) {
263
+ if (typeof remoteAddress !== "string") return "";
264
+ const zoneIndex = remoteAddress.indexOf("%");
265
+ const bare = zoneIndex === -1 ? remoteAddress : remoteAddress.slice(0, zoneIndex);
266
+ const family = net.isIP(bare);
267
+ if (zoneIndex !== -1) return family === IPV6 ? bare : "";
268
+ return family === 0 ? "" : bare;
269
+ }
270
+ function resolveClientAddress(request) {
271
+ const hops = request.ips ?? [];
272
+ for (const candidate of [request.ip, ...hops]) {
273
+ if (isHeaderAddress(candidate)) return candidate;
274
+ }
275
+ return peerAddress(request.socket?.remoteAddress);
276
+ }
231
277
  exports.ConnectionRegistry = class ConnectionRegistry {
232
278
  byId = /* @__PURE__ */ new Map();
233
279
  byUserId = /* @__PURE__ */ new Map();
@@ -396,6 +442,46 @@ var ROOM_PREFIXES = {
396
442
  function composeRoomId(prefix, ...parts) {
397
443
  return [ROOM_PREFIXES[prefix], ...parts].join(":");
398
444
  }
445
+
446
+ // src/server/utils/unavailable-error.ts
447
+ function unavailableError(code, who, what, cause) {
448
+ return new Error(`[${who}] ${code}: ${what} (${describeError(cause)})`, { cause });
449
+ }
450
+ exports.InMemoryPubSub = class InMemoryPubSub {
451
+ handlers = /* @__PURE__ */ new Set();
452
+ /**
453
+ * Publish a message to all subscribed handlers.
454
+ *
455
+ * Delivery is deferred one microtask so a handler that enqueues further publishes
456
+ * does not deepen the current call stack. One handler's failure does not block others.
457
+ *
458
+ * @param message - The pub/sub message to fan out.
459
+ */
460
+ async publish(message) {
461
+ await Promise.resolve();
462
+ for (const handler of this.handlers) {
463
+ try {
464
+ handler(message);
465
+ } catch {
466
+ }
467
+ }
468
+ }
469
+ /**
470
+ * Subscribe to pub/sub messages.
471
+ *
472
+ * @param handler - Called for every published message.
473
+ * @returns An async unsubscribe function that removes this handler.
474
+ */
475
+ async subscribe(handler) {
476
+ this.handlers.add(handler);
477
+ return async () => {
478
+ this.handlers.delete(handler);
479
+ };
480
+ }
481
+ };
482
+ exports.InMemoryPubSub = __decorateClass([
483
+ common.Injectable()
484
+ ], exports.InMemoryPubSub);
399
485
  var DEFAULT_REPLAY_BUFFER_SIZE = 100;
400
486
  exports.EventReplayBuffer = class EventReplayBuffer {
401
487
  constructor(opts) {
@@ -608,15 +694,59 @@ exports.SseTransport = class SseTransport {
608
694
  getConnection(connectionId) {
609
695
  return this.connections.get(connectionId);
610
696
  }
697
+ /**
698
+ * Emit to a user: live here, to the other instances over the bus, and into the offline queue
699
+ * when the user has no live connection on this instance.
700
+ *
701
+ * A failed publish or a failed append is reported (log and `onDeliveryFailure`) and the call
702
+ * still resolves, since delivery to the other instances is at-most-once. It rejects only when
703
+ * the event has no delivery path left: the user is offline here, the queue could not keep it,
704
+ * and the bus either failed or cannot reach another instance (the in-memory bus). A rejection
705
+ * carries the queue failure as its cause and is not also reported to the hook.
706
+ */
611
707
  async emitToUser(userId, event, data) {
612
708
  const id = this.idGen.next();
613
709
  this.emitToUserLocal(userId, event, data, id);
614
- if (this.offlineQueue && this.connections.byUser(userId, "sse").length === 0) {
615
- void this.offlineQueue.append(userId, { id, event, data, emittedAt: /* @__PURE__ */ new Date() }).catch(
616
- (error) => this.logger.warn(`Offline queue append failed: ${describeError(error)}`)
710
+ const queue = this.offlineQueue;
711
+ const offline = queue !== void 0 && this.connections.byUser(userId, "sse").length === 0;
712
+ const [queueFailure, publishFailure] = await Promise.all([
713
+ offline ? this.tryAppend(queue, userId, { id, event, data, emittedAt: /* @__PURE__ */ new Date() }) : void 0,
714
+ this.tryPublish({ op: "emitToUser", args: { userId, event, data, id } })
715
+ ]);
716
+ if (queueFailure !== void 0 && (publishFailure !== void 0 || !this.busReachesOtherInstances())) {
717
+ throw unavailableError(
718
+ REALTIME_ERROR_CODES.TRANSPORT_UNAVAILABLE,
719
+ exports.SseTransport.name,
720
+ `${event} for ${userId} has no delivery path: the user is offline here and the offline queue failed`,
721
+ queueFailure.error
617
722
  );
618
723
  }
619
- await this.publish({ op: "emitToUser", args: { userId, event, data, id } });
724
+ if (publishFailure !== void 0) this.reportPublishFailure("emitToUser", publishFailure);
725
+ if (queueFailure !== void 0) {
726
+ reportDeliveryFailure(
727
+ this.logger,
728
+ this.hooks,
729
+ {
730
+ code: REALTIME_ERROR_CODES.TRANSPORT_UNAVAILABLE,
731
+ op: "offlineAppend",
732
+ error: queueFailure.error
733
+ },
734
+ "Offline queue append failed"
735
+ );
736
+ }
737
+ }
738
+ /** Append to the offline queue; resolves with the failure, or `undefined` once it is kept. */
739
+ async tryAppend(queue, userId, event) {
740
+ try {
741
+ await queue.append(userId, event);
742
+ return void 0;
743
+ } catch (error) {
744
+ return { error };
745
+ }
746
+ }
747
+ /** Whether the bus can carry an event to another instance (the in-memory bus cannot). */
748
+ busReachesOtherInstances() {
749
+ return !(this.pubsub instanceof exports.InMemoryPubSub);
620
750
  }
621
751
  async emitToTenant(tenantId, event, data) {
622
752
  const id = this.idGen.next();
@@ -633,20 +763,44 @@ exports.SseTransport = class SseTransport {
633
763
  this.broadcastLocal(event, data, id);
634
764
  await this.publish({ op: "broadcast", args: { event, data, id } });
635
765
  }
766
+ /** Join a connection this instance holds to a room; any other id is left alone. */
636
767
  async joinRoom(connectionId, roomId) {
637
- this.rooms.join(connectionId, roomId);
768
+ if (this.connections.get(connectionId)?.transport === "sse")
769
+ this.rooms.join(connectionId, roomId);
638
770
  }
771
+ /** Remove a connection this instance holds from a room; any other id is left alone. */
639
772
  async leaveRoom(connectionId, roomId) {
640
- this.rooms.leave(connectionId, roomId);
773
+ if (this.connections.get(connectionId)?.transport === "sse")
774
+ this.rooms.leave(connectionId, roomId);
641
775
  }
642
- /** Disconnect a connection locally if owned here, otherwise revoke cross-instance. */
776
+ /**
777
+ * Disconnect a connection locally if owned here, otherwise revoke cross-instance.
778
+ *
779
+ * Resolves once the connection is closed here or the revocation has been handed to the bus. A
780
+ * connection held here as a WebSocket is left to the WebSocket transport and nothing is
781
+ * published. It rejects with `REALTIME_PUBSUB_UNAVAILABLE` when the bus refuses it: nothing has reached
782
+ * the connection, so the caller must not read the resolution as a revocation.
783
+ */
643
784
  async disconnect(connectionId, reason) {
644
785
  const record = this.connections.get(connectionId);
645
- if (record && record.transport === "sse") {
786
+ if (record) {
646
787
  await this.disconnectLocal(connectionId, reason);
647
788
  return;
648
789
  }
649
- await this.publish({ op: "disconnect", args: { connectionId, reason } });
790
+ try {
791
+ await this.pubsub.publish({
792
+ op: "disconnect",
793
+ args: { connectionId, reason },
794
+ origin: this.instanceId
795
+ });
796
+ } catch (error) {
797
+ throw unavailableError(
798
+ REALTIME_ERROR_CODES.PUBSUB_UNAVAILABLE,
799
+ exports.SseTransport.name,
800
+ `the revocation of ${connectionId} could not be published`,
801
+ error
802
+ );
803
+ }
650
804
  }
651
805
  /**
652
806
  * Deliver an event to a user's local SSE connections and update the replay buffer.
@@ -722,14 +876,28 @@ exports.SseTransport = class SseTransport {
722
876
  this.logger.warn(`SSE delivery failed for ${conn.connectionId}: ${describeError(error)}`);
723
877
  }
724
878
  }
725
- /** Publish once to the bus; pub/sub failures never affect the live emit path. */
726
- async publish(message) {
879
+ /** Publish once to the bus; resolves with the failure, or `undefined` once the bus accepted it. */
880
+ async tryPublish(message) {
727
881
  try {
728
882
  await this.pubsub.publish({ ...message, origin: this.instanceId });
883
+ return void 0;
729
884
  } catch (error) {
730
- this.logger.warn(`pubsub.publish failed: ${describeError(error)}`);
885
+ return { error };
731
886
  }
732
887
  }
888
+ /** Publish once to the bus. A failure is reported and never fails the live emit path. */
889
+ async publish(message) {
890
+ const failure = await this.tryPublish(message);
891
+ if (failure !== void 0) this.reportPublishFailure(message.op, failure);
892
+ }
893
+ reportPublishFailure(op, { error }) {
894
+ reportDeliveryFailure(
895
+ this.logger,
896
+ this.hooks,
897
+ { code: REALTIME_ERROR_CODES.PUBSUB_UNAVAILABLE, op, error },
898
+ "pubsub.publish failed"
899
+ );
900
+ }
733
901
  /** Evict a user's oldest connections (FIFO) when over `maxConnectionsPerUser`. */
734
902
  async evictBeyondLimit(userId) {
735
903
  const max = this.options.sse?.maxConnectionsPerUser;
@@ -762,11 +930,6 @@ exports.SseTransport = __decorateClass([
762
930
  function singleHeader(value) {
763
931
  return typeof value === "string" ? value : void 0;
764
932
  }
765
- function resolveIp(req) {
766
- const forwarded = req.headers["x-forwarded-for"];
767
- const candidate = (typeof forwarded === "string" ? forwarded.split(",")[0] : void 0) ?? "";
768
- return candidate.trim() || req.ip || "unknown";
769
- }
770
933
  function normalizeHeaders(headers) {
771
934
  const out = /* @__PURE__ */ Object.create(null);
772
935
  for (const [key, value] of Object.entries(headers)) {
@@ -788,7 +951,7 @@ function buildAuthContext(req) {
788
951
  cookies: parseCookieHeader(singleHeader(req.headers["cookie"]) ?? ""),
789
952
  headers,
790
953
  query: sanitizeQuery(req.query),
791
- ip: resolveIp(req),
954
+ ip: resolveClientAddress(req),
792
955
  remoteAddress: req.socket?.remoteAddress,
793
956
  userAgent: singleHeader(req.headers["user-agent"]),
794
957
  transport: "sse"
@@ -1103,46 +1266,29 @@ function createSseController(endpoint) {
1103
1266
  ], DynamicSseController);
1104
1267
  return DynamicSseController;
1105
1268
  }
1106
- exports.InMemoryPubSub = class InMemoryPubSub {
1107
- handlers = /* @__PURE__ */ new Set();
1108
- /**
1109
- * Publish a message to all subscribed handlers.
1110
- *
1111
- * Delivery is deferred one microtask so a handler that enqueues further publishes
1112
- * does not deepen the current call stack. One handler's failure does not block others.
1113
- *
1114
- * @param message - The pub/sub message to fan out.
1115
- */
1116
- async publish(message) {
1117
- await Promise.resolve();
1118
- for (const handler of this.handlers) {
1119
- try {
1120
- handler(message);
1121
- } catch {
1122
- }
1123
- }
1269
+ exports.RealtimeService = class RealtimeService {
1270
+ constructor(transport, pubsub) {
1271
+ this.transport = transport;
1272
+ this.pubsub = pubsub;
1124
1273
  }
1274
+ transport;
1275
+ pubsub;
1125
1276
  /**
1126
- * Subscribe to pub/sub messages.
1277
+ * Whether this instance hears the events and revocations other instances publish. False while
1278
+ * the bus is unreachable or its subscriber connection is down, so a readiness probe can take a
1279
+ * deaf instance out of rotation. True for a bus that does not report a state, and with
1280
+ * `transport: 'websocket'`, which does not subscribe to the bus.
1127
1281
  *
1128
- * @param handler - Called for every published message.
1129
- * @returns An async unsubscribe function that removes this handler.
1282
+ * @example
1283
+ * ```ts
1284
+ * // In a health indicator: `isHealthy` is false while the instance cannot hear the others.
1285
+ * return indicator.check('realtime', realtime.isPubSubReady())
1286
+ * ```
1130
1287
  */
1131
- async subscribe(handler) {
1132
- this.handlers.add(handler);
1133
- return async () => {
1134
- this.handlers.delete(handler);
1135
- };
1136
- }
1137
- };
1138
- exports.InMemoryPubSub = __decorateClass([
1139
- common.Injectable()
1140
- ], exports.InMemoryPubSub);
1141
- exports.RealtimeService = class RealtimeService {
1142
- constructor(transport) {
1143
- this.transport = transport;
1288
+ isPubSubReady() {
1289
+ if (this.transport.kind === "websocket") return true;
1290
+ return this.pubsub?.isSubscribed?.() ?? true;
1144
1291
  }
1145
- transport;
1146
1292
  /**
1147
1293
  * Send to all of a user's connections (across devices/tabs).
1148
1294
  *
@@ -1175,22 +1321,41 @@ exports.RealtimeService = class RealtimeService {
1175
1321
  * The room id is not checked. Never pass client-supplied input that could start
1176
1322
  * with the reserved `user:` or `tenant:` prefixes: joining `tenant:<other>`
1177
1323
  * receives that tenant's events.
1324
+ *
1325
+ * Acts on a connection this instance holds; for any other id it resolves and changes
1326
+ * nothing. A failure of the transport that holds the connection rejects the call.
1178
1327
  */
1179
1328
  joinRoom(connectionId, roomId) {
1180
1329
  return this.transport.joinRoom(connectionId, roomId);
1181
1330
  }
1182
- /** Remove a specific connection from a room. */
1331
+ /**
1332
+ * Remove a specific connection from a room.
1333
+ *
1334
+ * Acts on a connection this instance holds; for any other id it resolves and changes
1335
+ * nothing. A failure of the transport that holds the connection rejects the call.
1336
+ */
1183
1337
  leaveRoom(connectionId, roomId) {
1184
1338
  return this.transport.leaveRoom(connectionId, roomId);
1185
1339
  }
1186
- /** Force-disconnect a specific connection (e.g. on auth revocation). */
1340
+ /**
1341
+ * Force-disconnect a specific connection (e.g. on auth revocation).
1342
+ *
1343
+ * Resolves once the connection is closed on this instance or the revocation has been handed
1344
+ * to the bus for the instance that holds it.
1345
+ *
1346
+ * @throws {Error} `REALTIME_PUBSUB_UNAVAILABLE` when the bus refuses the revocation, or
1347
+ * `REALTIME_TRANSPORT_UNAVAILABLE` when the transport that holds the connection fails.
1348
+ * The connection may still be connected: retry.
1349
+ */
1187
1350
  disconnect(connectionId, reason) {
1188
1351
  return this.transport.disconnect(connectionId, reason);
1189
1352
  }
1190
1353
  };
1191
1354
  exports.RealtimeService = __decorateClass([
1192
1355
  common.Injectable(),
1193
- __decorateParam(0, common.Inject(REALTIME_TRANSPORT_TOKEN))
1356
+ __decorateParam(0, common.Inject(REALTIME_TRANSPORT_TOKEN)),
1357
+ __decorateParam(1, common.Optional()),
1358
+ __decorateParam(1, common.Inject(REALTIME_PUBSUB_TOKEN))
1194
1359
  ], exports.RealtimeService);
1195
1360
  function resolvePolicy(raw) {
1196
1361
  return {
@@ -1228,7 +1393,11 @@ exports.ReauthenticationService = class ReauthenticationService {
1228
1393
  this.logger.log("Authenticator does not implement revalidate() \u2014 reauthentication disabled");
1229
1394
  return;
1230
1395
  }
1231
- this.timer = setInterval(() => void this.runCycle(), this.policy.intervalSeconds * 1e3);
1396
+ this.timer = setInterval(() => {
1397
+ this.runCycle().catch((err) => {
1398
+ this.logger.warn(`Reauthentication cycle failed: ${describeError(err)}`);
1399
+ });
1400
+ }, this.policy.intervalSeconds * 1e3);
1232
1401
  this.timer.unref();
1233
1402
  this.logger.log(`Reauthentication scheduled every ${this.policy.intervalSeconds}s`);
1234
1403
  }
@@ -1274,13 +1443,27 @@ exports.ReauthenticationService = class ReauthenticationService {
1274
1443
  this.positiveCache.set(conn.connectionId, now);
1275
1444
  continue;
1276
1445
  }
1277
- await this.handleFailure(conn);
1446
+ await this.revoke(conn);
1278
1447
  } catch (err) {
1279
1448
  this.logger.warn(`Reauthentication errored for ${conn.connectionId}: ${describeError(err)}`);
1280
- await this.handleFailure(conn);
1449
+ await this.revoke(conn);
1281
1450
  }
1282
1451
  }
1283
1452
  }
1453
+ /**
1454
+ * Revoke a connection whose revalidation failed, and keep the cycle going when the
1455
+ * revocation itself is rejected. The positive-cache entry is already gone, so the next
1456
+ * cycle revalidates the connection and tries again.
1457
+ */
1458
+ async revoke(conn) {
1459
+ try {
1460
+ await this.handleFailure(conn);
1461
+ } catch (err) {
1462
+ this.logger.warn(
1463
+ `Revocation of ${conn.connectionId} failed, retrying next cycle: ${describeError(err)}`
1464
+ );
1465
+ }
1466
+ }
1284
1467
  /** Evict the positive-cache entry, optionally emit the failure event, then disconnect. */
1285
1468
  async handleFailure(conn) {
1286
1469
  this.positiveCache.delete(conn.connectionId);
@@ -1493,13 +1676,7 @@ exports.RealtimePubSubSubscriber = class RealtimePubSubSubscriber {
1493
1676
  logger = new common.Logger(exports.RealtimePubSubSubscriber.name);
1494
1677
  unsubscribe = null;
1495
1678
  async onModuleInit() {
1496
- try {
1497
- this.unsubscribe = await this.pubsub.subscribe((msg) => this.handle(msg));
1498
- } catch (err) {
1499
- this.logger.warn(
1500
- `Failed to subscribe to pub/sub: ${describeError(err)}. Cross-instance fan-out disabled; remote events will not reach this instance.`
1501
- );
1502
- }
1679
+ this.unsubscribe = await this.pubsub.subscribe((msg) => this.handle(msg));
1503
1680
  }
1504
1681
  async onApplicationShutdown() {
1505
1682
  if (this.unsubscribe) {
@@ -1537,7 +1714,13 @@ exports.RealtimePubSubSubscriber = class RealtimePubSubSubscriber {
1537
1714
  }
1538
1715
  case "disconnect": {
1539
1716
  const a = msg.args;
1540
- void this.sse.disconnectLocal(a.connectionId, a.reason);
1717
+ Promise.resolve(this.sse.disconnectLocal(a.connectionId, a.reason)).catch(
1718
+ (err) => {
1719
+ this.logger.warn(
1720
+ `Remote disconnect of ${a.connectionId} failed: ${describeError(err)}`
1721
+ );
1722
+ }
1723
+ );
1541
1724
  break;
1542
1725
  }
1543
1726
  default: {
@@ -1645,9 +1828,13 @@ exports.BymaxRealtimeModule = __decorateClass([
1645
1828
  common.Global(),
1646
1829
  common.Module({})
1647
1830
  ], exports.BymaxRealtimeModule);
1648
-
1649
- // src/server/pubsub/redis-realtime-pubsub.ts
1650
- var RedisRealtimePubSub = class {
1831
+ var MALFORMED_REPORT_INTERVAL_MS = 6e4;
1832
+ function connectionReason(err) {
1833
+ const code = err?.code;
1834
+ const text = describeError(err);
1835
+ return [typeof code === "string" ? code : "", text].filter(Boolean).join(" ") || String(err);
1836
+ }
1837
+ var RedisRealtimePubSub = class _RedisRealtimePubSub {
1651
1838
  /**
1652
1839
  * The publishing Redis client.
1653
1840
  *
@@ -1661,10 +1848,29 @@ var RedisRealtimePubSub = class {
1661
1848
  /** The lazily created subscriber connection, which carries the same credentials. */
1662
1849
  #subInit = null;
1663
1850
  handlers = /* @__PURE__ */ new Set();
1851
+ logger = new common.Logger(_RedisRealtimePubSub.name);
1852
+ /** Payloads dropped as unparsable since the last report, and when that report was made. */
1853
+ malformedDropped = 0;
1854
+ malformedReportedAt = 0;
1855
+ /** Whether the subscriber connection holds a confirmed SUBSCRIBE right now. */
1856
+ #subscribed = false;
1857
+ /** Whether the current outage has been logged, so a retry loop adds no line. */
1858
+ // Stryker disable next-line BooleanLiteral: equivalent — createSubscriber sets it before any use
1859
+ #outageLogged = false;
1860
+ /** Connections closed on purpose, whose `close` is not an outage and says nothing of a successor. */
1861
+ #retired = /* @__PURE__ */ new WeakSet();
1664
1862
  constructor(options) {
1665
1863
  this.#pub = options.client;
1666
1864
  this.channel = options.channel ?? "bymax:realtime";
1667
1865
  }
1866
+ /**
1867
+ * Whether this instance holds a confirmed subscription to the channel, so the events and
1868
+ * revocations other instances publish reach it. False before the first successful subscribe,
1869
+ * while the subscriber connection is down, and after the last handler has unsubscribed.
1870
+ */
1871
+ isSubscribed() {
1872
+ return this.#subscribed;
1873
+ }
1668
1874
  /** JSON-encodes the message and PUBLISHes it to the configured channel. */
1669
1875
  async publish(message) {
1670
1876
  await this.#pub.publish(this.channel, JSON.stringify(message));
@@ -1673,7 +1879,7 @@ var RedisRealtimePubSub = class {
1673
1879
  * Lazily creates the single shared subscribe client on first call; returns an async
1674
1880
  * unsubscribe that quits the client when the last handler is removed. Concurrent
1675
1881
  * subscribe calls are idempotent — only one client is ever created. Malformed
1676
- * payloads are dropped silently.
1882
+ * payloads are dropped, and reported at most once a minute with their count.
1677
1883
  *
1678
1884
  * If the subscriber client cannot be created (e.g. Redis temporarily unavailable),
1679
1885
  * the handler registration is rolled back and the cached init promise is cleared so
@@ -1693,8 +1899,12 @@ var RedisRealtimePubSub = class {
1693
1899
  this.handlers.delete(handler);
1694
1900
  if (this.handlers.size === 0) {
1695
1901
  this.#subInit = null;
1902
+ this.#retired.add(sub);
1903
+ const connected = this.#subscribed;
1904
+ this.#subscribed = false;
1696
1905
  try {
1697
- await sub.quit();
1906
+ if (connected) await sub.quit();
1907
+ else sub.disconnect();
1698
1908
  } catch {
1699
1909
  }
1700
1910
  }
@@ -1706,16 +1916,97 @@ var RedisRealtimePubSub = class {
1706
1916
  return this.#subInit;
1707
1917
  }
1708
1918
  async createSubscriber() {
1709
- const sub = this.#pub.duplicate();
1710
- await sub.subscribe(this.channel);
1919
+ this.#outageLogged = false;
1920
+ const sub = this.#pub.duplicate({ autoResubscribe: false });
1921
+ let attached = false;
1711
1922
  sub.on("message", (_ch, payload) => this.dispatch(payload));
1923
+ const unreachableFirst = new Promise((resolve) => {
1924
+ sub.on("error", (err) => {
1925
+ if (err.name !== "ReplyError") resolve({ unreachable: err });
1926
+ });
1927
+ sub.on("close", () => {
1928
+ resolve({ unreachable: new Error() });
1929
+ if (!this.#retired.has(sub)) this.markDown("connection closed");
1930
+ });
1931
+ });
1932
+ sub.on("ready", () => {
1933
+ if (attached) this.confirm(sub);
1934
+ });
1935
+ const first = sub.subscribe(this.channel);
1936
+ try {
1937
+ const outcome = await Promise.race([
1938
+ first.then(() => "subscribed"),
1939
+ unreachableFirst
1940
+ ]);
1941
+ if (outcome === "subscribed") {
1942
+ this.markUp();
1943
+ } else {
1944
+ this.markDown(connectionReason(outcome.unreachable));
1945
+ first.catch((err) => this.refused(err));
1946
+ }
1947
+ } catch (err) {
1948
+ this.#retired.add(sub);
1949
+ sub.disconnect();
1950
+ throw unavailableError(
1951
+ REALTIME_ERROR_CODES.PUBSUB_UNAVAILABLE,
1952
+ _RedisRealtimePubSub.name,
1953
+ `could not subscribe to "${this.channel}"`,
1954
+ err
1955
+ );
1956
+ }
1957
+ attached = true;
1712
1958
  return sub;
1713
1959
  }
1960
+ confirm(sub) {
1961
+ sub.subscribe(this.channel).then(
1962
+ () => this.markUp(),
1963
+ (err) => this.refused(err)
1964
+ );
1965
+ }
1966
+ /** A server that was reached and refused the SUBSCRIBE after boot: it stays unsubscribed. */
1967
+ refused(err) {
1968
+ if (err?.name !== "ReplyError") return;
1969
+ this.#subscribed = false;
1970
+ this.logger.warn(
1971
+ `${REALTIME_ERROR_CODES.PUBSUB_UNAVAILABLE}: the server refused the subscription to "${this.channel}": ${describeError(err)}`
1972
+ );
1973
+ }
1974
+ markUp() {
1975
+ if (this.#subscribed) return;
1976
+ this.#subscribed = true;
1977
+ this.#outageLogged = false;
1978
+ this.logger.log(
1979
+ `Subscribed to "${this.channel}"; remote events and revocations reach this instance`
1980
+ );
1981
+ }
1982
+ markDown(reason) {
1983
+ this.#subscribed = false;
1984
+ if (this.#outageLogged) return;
1985
+ this.#outageLogged = true;
1986
+ this.logger.warn(
1987
+ `${REALTIME_ERROR_CODES.PUBSUB_UNAVAILABLE}: not subscribed to "${this.channel}": ${reason}. Remote events and revocations will not reach this instance until it subscribes again`
1988
+ );
1989
+ }
1990
+ /**
1991
+ * Count a payload dropped as unparsable and report the count at most once per minute, so a
1992
+ * producer on an incompatible version is visible without flooding the log.
1993
+ */
1994
+ reportMalformed() {
1995
+ this.malformedDropped++;
1996
+ const now = Date.now();
1997
+ if (now - this.malformedReportedAt < MALFORMED_REPORT_INTERVAL_MS) return;
1998
+ this.logger.warn(
1999
+ `${REALTIME_ERROR_CODES.PUBSUB_UNAVAILABLE}: dropped ${this.malformedDropped} malformed payload(s) on "${this.channel}" since the last report`
2000
+ );
2001
+ this.malformedDropped = 0;
2002
+ this.malformedReportedAt = now;
2003
+ }
1714
2004
  dispatch(payload) {
1715
2005
  let msg;
1716
2006
  try {
1717
2007
  msg = JSON.parse(payload);
1718
2008
  } catch {
2009
+ this.reportMalformed();
1719
2010
  return;
1720
2011
  }
1721
2012
  for (const h of this.handlers) {
@@ -1833,5 +2124,7 @@ exports.composeRoomId = composeRoomId;
1833
2124
  exports.createSseController = createSseController;
1834
2125
  exports.describeError = describeError;
1835
2126
  exports.parseCookieHeader = parseCookieHeader;
2127
+ exports.reportDeliveryFailure = reportDeliveryFailure;
1836
2128
  exports.resolveAuthTenant = resolveAuthTenant;
1837
2129
  exports.sseWiring = sseWiring;
2130
+ exports.unavailableError = unavailableError;