@bymax-one/nest-realtime 1.2.6 → 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.
@@ -29,6 +29,7 @@ var REALTIME_ERROR_CODES = {
29
29
  TOO_MANY_CONNECTIONS: "REALTIME_TOO_MANY_CONNECTIONS",
30
30
  INVALID_TICKET: "REALTIME_INVALID_TICKET",
31
31
  PUBSUB_UNAVAILABLE: "REALTIME_PUBSUB_UNAVAILABLE",
32
+ TRANSPORT_UNAVAILABLE: "REALTIME_TRANSPORT_UNAVAILABLE",
32
33
  REDIS_ADAPTER_FAILED: "REALTIME_REDIS_ADAPTER_FAILED",
33
34
  PAYLOAD_TOO_LARGE: "REALTIME_PAYLOAD_TOO_LARGE",
34
35
  REPLAY_BUFFER_MISS: "REALTIME_REPLAY_BUFFER_MISS"
@@ -117,13 +118,27 @@ function describeError(reason) {
117
118
  }
118
119
  }
119
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
+
120
133
  // src/server/offline-queue/offline-queue-delivery.service.ts
121
134
  var RETRIEVE_LIMIT = 200;
122
135
  exports.OfflineQueueDeliveryService = class OfflineQueueDeliveryService {
123
- constructor(storage) {
136
+ constructor(storage, hooks) {
124
137
  this.storage = storage;
138
+ this.hooks = hooks;
125
139
  }
126
140
  storage;
141
+ hooks;
127
142
  logger = new common.Logger(exports.OfflineQueueDeliveryService.name);
128
143
  /**
129
144
  * Return events for `userId` that arrived after `lastEventId` and are NOT
@@ -144,7 +159,16 @@ exports.OfflineQueueDeliveryService = class OfflineQueueDeliveryService {
144
159
  try {
145
160
  events = await this.storage.retrieveSince(userId, lastEventId, RETRIEVE_LIMIT);
146
161
  } catch (err) {
147
- 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
+ );
148
172
  return [];
149
173
  }
150
174
  if (events.length === RETRIEVE_LIMIT) {
@@ -178,7 +202,9 @@ exports.OfflineQueueDeliveryService = class OfflineQueueDeliveryService {
178
202
  exports.OfflineQueueDeliveryService = __decorateClass([
179
203
  common.Injectable(),
180
204
  __decorateParam(0, common.Optional()),
181
- __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))
182
208
  ], exports.OfflineQueueDeliveryService);
183
209
 
184
210
  // src/shared/constants/reserved-events.constants.ts
@@ -416,6 +442,46 @@ var ROOM_PREFIXES = {
416
442
  function composeRoomId(prefix, ...parts) {
417
443
  return [ROOM_PREFIXES[prefix], ...parts].join(":");
418
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);
419
485
  var DEFAULT_REPLAY_BUFFER_SIZE = 100;
420
486
  exports.EventReplayBuffer = class EventReplayBuffer {
421
487
  constructor(opts) {
@@ -628,15 +694,59 @@ exports.SseTransport = class SseTransport {
628
694
  getConnection(connectionId) {
629
695
  return this.connections.get(connectionId);
630
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
+ */
631
707
  async emitToUser(userId, event, data) {
632
708
  const id = this.idGen.next();
633
709
  this.emitToUserLocal(userId, event, data, id);
634
- if (this.offlineQueue && this.connections.byUser(userId, "sse").length === 0) {
635
- void this.offlineQueue.append(userId, { id, event, data, emittedAt: /* @__PURE__ */ new Date() }).catch(
636
- (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
637
722
  );
638
723
  }
639
- 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);
640
750
  }
641
751
  async emitToTenant(tenantId, event, data) {
642
752
  const id = this.idGen.next();
@@ -653,20 +763,44 @@ exports.SseTransport = class SseTransport {
653
763
  this.broadcastLocal(event, data, id);
654
764
  await this.publish({ op: "broadcast", args: { event, data, id } });
655
765
  }
766
+ /** Join a connection this instance holds to a room; any other id is left alone. */
656
767
  async joinRoom(connectionId, roomId) {
657
- this.rooms.join(connectionId, roomId);
768
+ if (this.connections.get(connectionId)?.transport === "sse")
769
+ this.rooms.join(connectionId, roomId);
658
770
  }
771
+ /** Remove a connection this instance holds from a room; any other id is left alone. */
659
772
  async leaveRoom(connectionId, roomId) {
660
- this.rooms.leave(connectionId, roomId);
773
+ if (this.connections.get(connectionId)?.transport === "sse")
774
+ this.rooms.leave(connectionId, roomId);
661
775
  }
662
- /** 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
+ */
663
784
  async disconnect(connectionId, reason) {
664
785
  const record = this.connections.get(connectionId);
665
- if (record && record.transport === "sse") {
786
+ if (record) {
666
787
  await this.disconnectLocal(connectionId, reason);
667
788
  return;
668
789
  }
669
- 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
+ }
670
804
  }
671
805
  /**
672
806
  * Deliver an event to a user's local SSE connections and update the replay buffer.
@@ -742,14 +876,28 @@ exports.SseTransport = class SseTransport {
742
876
  this.logger.warn(`SSE delivery failed for ${conn.connectionId}: ${describeError(error)}`);
743
877
  }
744
878
  }
745
- /** Publish once to the bus; pub/sub failures never affect the live emit path. */
746
- async publish(message) {
879
+ /** Publish once to the bus; resolves with the failure, or `undefined` once the bus accepted it. */
880
+ async tryPublish(message) {
747
881
  try {
748
882
  await this.pubsub.publish({ ...message, origin: this.instanceId });
883
+ return void 0;
749
884
  } catch (error) {
750
- this.logger.warn(`pubsub.publish failed: ${describeError(error)}`);
885
+ return { error };
751
886
  }
752
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
+ }
753
901
  /** Evict a user's oldest connections (FIFO) when over `maxConnectionsPerUser`. */
754
902
  async evictBeyondLimit(userId) {
755
903
  const max = this.options.sse?.maxConnectionsPerUser;
@@ -1118,46 +1266,29 @@ function createSseController(endpoint) {
1118
1266
  ], DynamicSseController);
1119
1267
  return DynamicSseController;
1120
1268
  }
1121
- exports.InMemoryPubSub = class InMemoryPubSub {
1122
- handlers = /* @__PURE__ */ new Set();
1123
- /**
1124
- * Publish a message to all subscribed handlers.
1125
- *
1126
- * Delivery is deferred one microtask so a handler that enqueues further publishes
1127
- * does not deepen the current call stack. One handler's failure does not block others.
1128
- *
1129
- * @param message - The pub/sub message to fan out.
1130
- */
1131
- async publish(message) {
1132
- await Promise.resolve();
1133
- for (const handler of this.handlers) {
1134
- try {
1135
- handler(message);
1136
- } catch {
1137
- }
1138
- }
1269
+ exports.RealtimeService = class RealtimeService {
1270
+ constructor(transport, pubsub) {
1271
+ this.transport = transport;
1272
+ this.pubsub = pubsub;
1139
1273
  }
1274
+ transport;
1275
+ pubsub;
1140
1276
  /**
1141
- * 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.
1142
1281
  *
1143
- * @param handler - Called for every published message.
1144
- * @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
+ * ```
1145
1287
  */
1146
- async subscribe(handler) {
1147
- this.handlers.add(handler);
1148
- return async () => {
1149
- this.handlers.delete(handler);
1150
- };
1151
- }
1152
- };
1153
- exports.InMemoryPubSub = __decorateClass([
1154
- common.Injectable()
1155
- ], exports.InMemoryPubSub);
1156
- exports.RealtimeService = class RealtimeService {
1157
- constructor(transport) {
1158
- this.transport = transport;
1288
+ isPubSubReady() {
1289
+ if (this.transport.kind === "websocket") return true;
1290
+ return this.pubsub?.isSubscribed?.() ?? true;
1159
1291
  }
1160
- transport;
1161
1292
  /**
1162
1293
  * Send to all of a user's connections (across devices/tabs).
1163
1294
  *
@@ -1190,22 +1321,41 @@ exports.RealtimeService = class RealtimeService {
1190
1321
  * The room id is not checked. Never pass client-supplied input that could start
1191
1322
  * with the reserved `user:` or `tenant:` prefixes: joining `tenant:<other>`
1192
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.
1193
1327
  */
1194
1328
  joinRoom(connectionId, roomId) {
1195
1329
  return this.transport.joinRoom(connectionId, roomId);
1196
1330
  }
1197
- /** 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
+ */
1198
1337
  leaveRoom(connectionId, roomId) {
1199
1338
  return this.transport.leaveRoom(connectionId, roomId);
1200
1339
  }
1201
- /** 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
+ */
1202
1350
  disconnect(connectionId, reason) {
1203
1351
  return this.transport.disconnect(connectionId, reason);
1204
1352
  }
1205
1353
  };
1206
1354
  exports.RealtimeService = __decorateClass([
1207
1355
  common.Injectable(),
1208
- __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))
1209
1359
  ], exports.RealtimeService);
1210
1360
  function resolvePolicy(raw) {
1211
1361
  return {
@@ -1243,7 +1393,11 @@ exports.ReauthenticationService = class ReauthenticationService {
1243
1393
  this.logger.log("Authenticator does not implement revalidate() \u2014 reauthentication disabled");
1244
1394
  return;
1245
1395
  }
1246
- 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);
1247
1401
  this.timer.unref();
1248
1402
  this.logger.log(`Reauthentication scheduled every ${this.policy.intervalSeconds}s`);
1249
1403
  }
@@ -1289,13 +1443,27 @@ exports.ReauthenticationService = class ReauthenticationService {
1289
1443
  this.positiveCache.set(conn.connectionId, now);
1290
1444
  continue;
1291
1445
  }
1292
- await this.handleFailure(conn);
1446
+ await this.revoke(conn);
1293
1447
  } catch (err) {
1294
1448
  this.logger.warn(`Reauthentication errored for ${conn.connectionId}: ${describeError(err)}`);
1295
- await this.handleFailure(conn);
1449
+ await this.revoke(conn);
1296
1450
  }
1297
1451
  }
1298
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
+ }
1299
1467
  /** Evict the positive-cache entry, optionally emit the failure event, then disconnect. */
1300
1468
  async handleFailure(conn) {
1301
1469
  this.positiveCache.delete(conn.connectionId);
@@ -1508,13 +1676,7 @@ exports.RealtimePubSubSubscriber = class RealtimePubSubSubscriber {
1508
1676
  logger = new common.Logger(exports.RealtimePubSubSubscriber.name);
1509
1677
  unsubscribe = null;
1510
1678
  async onModuleInit() {
1511
- try {
1512
- this.unsubscribe = await this.pubsub.subscribe((msg) => this.handle(msg));
1513
- } catch (err) {
1514
- this.logger.warn(
1515
- `Failed to subscribe to pub/sub: ${describeError(err)}. Cross-instance fan-out disabled; remote events will not reach this instance.`
1516
- );
1517
- }
1679
+ this.unsubscribe = await this.pubsub.subscribe((msg) => this.handle(msg));
1518
1680
  }
1519
1681
  async onApplicationShutdown() {
1520
1682
  if (this.unsubscribe) {
@@ -1552,7 +1714,13 @@ exports.RealtimePubSubSubscriber = class RealtimePubSubSubscriber {
1552
1714
  }
1553
1715
  case "disconnect": {
1554
1716
  const a = msg.args;
1555
- 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
+ );
1556
1724
  break;
1557
1725
  }
1558
1726
  default: {
@@ -1660,9 +1828,13 @@ exports.BymaxRealtimeModule = __decorateClass([
1660
1828
  common.Global(),
1661
1829
  common.Module({})
1662
1830
  ], exports.BymaxRealtimeModule);
1663
-
1664
- // src/server/pubsub/redis-realtime-pubsub.ts
1665
- 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 {
1666
1838
  /**
1667
1839
  * The publishing Redis client.
1668
1840
  *
@@ -1676,10 +1848,29 @@ var RedisRealtimePubSub = class {
1676
1848
  /** The lazily created subscriber connection, which carries the same credentials. */
1677
1849
  #subInit = null;
1678
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();
1679
1862
  constructor(options) {
1680
1863
  this.#pub = options.client;
1681
1864
  this.channel = options.channel ?? "bymax:realtime";
1682
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
+ }
1683
1874
  /** JSON-encodes the message and PUBLISHes it to the configured channel. */
1684
1875
  async publish(message) {
1685
1876
  await this.#pub.publish(this.channel, JSON.stringify(message));
@@ -1688,7 +1879,7 @@ var RedisRealtimePubSub = class {
1688
1879
  * Lazily creates the single shared subscribe client on first call; returns an async
1689
1880
  * unsubscribe that quits the client when the last handler is removed. Concurrent
1690
1881
  * subscribe calls are idempotent — only one client is ever created. Malformed
1691
- * payloads are dropped silently.
1882
+ * payloads are dropped, and reported at most once a minute with their count.
1692
1883
  *
1693
1884
  * If the subscriber client cannot be created (e.g. Redis temporarily unavailable),
1694
1885
  * the handler registration is rolled back and the cached init promise is cleared so
@@ -1708,8 +1899,12 @@ var RedisRealtimePubSub = class {
1708
1899
  this.handlers.delete(handler);
1709
1900
  if (this.handlers.size === 0) {
1710
1901
  this.#subInit = null;
1902
+ this.#retired.add(sub);
1903
+ const connected = this.#subscribed;
1904
+ this.#subscribed = false;
1711
1905
  try {
1712
- await sub.quit();
1906
+ if (connected) await sub.quit();
1907
+ else sub.disconnect();
1713
1908
  } catch {
1714
1909
  }
1715
1910
  }
@@ -1721,16 +1916,97 @@ var RedisRealtimePubSub = class {
1721
1916
  return this.#subInit;
1722
1917
  }
1723
1918
  async createSubscriber() {
1724
- const sub = this.#pub.duplicate();
1725
- await sub.subscribe(this.channel);
1919
+ this.#outageLogged = false;
1920
+ const sub = this.#pub.duplicate({ autoResubscribe: false });
1921
+ let attached = false;
1726
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;
1727
1958
  return sub;
1728
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
+ }
1729
2004
  dispatch(payload) {
1730
2005
  let msg;
1731
2006
  try {
1732
2007
  msg = JSON.parse(payload);
1733
2008
  } catch {
2009
+ this.reportMalformed();
1734
2010
  return;
1735
2011
  }
1736
2012
  for (const h of this.handlers) {
@@ -1848,5 +2124,7 @@ exports.composeRoomId = composeRoomId;
1848
2124
  exports.createSseController = createSseController;
1849
2125
  exports.describeError = describeError;
1850
2126
  exports.parseCookieHeader = parseCookieHeader;
2127
+ exports.reportDeliveryFailure = reportDeliveryFailure;
1851
2128
  exports.resolveAuthTenant = resolveAuthTenant;
1852
2129
  exports.sseWiring = sseWiring;
2130
+ exports.unavailableError = unavailableError;