@bymax-one/nest-realtime 1.2.2 → 1.2.3

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/CHANGELOG.md CHANGED
@@ -7,6 +7,34 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
7
7
 
8
8
  ## [Unreleased]
9
9
 
10
+ ## [1.2.3] - 2026-10-31
11
+
12
+ **Apply before upgrading, if you set `websocket.redisAdapter`:** make sure `@socket.io/redis-adapter`
13
+ is installed and that `pubClient` is an ioredis client. 1.2.2 and earlier logged one error and served a single
14
+ instance when the adapter could not be installed, and every ESM consumer was in that state, so
15
+ WebSocket events did not cross instances. The boot now fails with `REALTIME_REDIS_ADAPTER_FAILED`
16
+ instead. A Redis that is merely unreachable does not fail the boot.
17
+
18
+ ### Fixed
19
+
20
+ - **The WebSocket Redis adapter now installs in the ES module build.** The adapter loaded
21
+ `@socket.io/redis-adapter` with a bare `require`, which an ES module does not have, so for every
22
+ consumer importing the package as ESM the load threw, one error line was logged, and the server
23
+ stayed single-instance: an emit on one instance never reached a client on another. Measured on the
24
+ published bundle with two instances and a real Redis, 0 of 5000 messages crossed; with the adapter
25
+ installed, 5000 of 5000 did. CommonJS consumers were not affected. The ESM bundle now declares a
26
+ `require` that resolves from the package, and still loads when a consumer's bundler re-bundles it
27
+ into CommonJS, where `import.meta.url` is undefined. `pnpm size` fails when an ESM bundle calls a
28
+ `require` it does not declare, and `pnpm check:runtime` boots the packed tarball in ESM, in
29
+ CommonJS and re-bundled into CommonJS, and asserts the adapter registers in each.
30
+
31
+ - **A WebSocket authenticator that rejects with a value that is not an `Error` no longer leaves the
32
+ socket connected.** The catch in `handleConnection` read `.message` from whatever was thrown, so a
33
+ rejection with `null` or `undefined` made the catch itself throw before `socket.disconnect(true)`
34
+ ran. The reason is now logged as `String(reason)` when it is not an `Error`, and the socket is
35
+ always closed. The handshake middleware already logged it this way; this is the path that runs when
36
+ the gateway is used without it.
37
+
10
38
  ## [1.2.2] - 2026-10-31
11
39
 
12
40
  ### Fixed
@@ -570,7 +598,8 @@ First published release.
570
598
  rather than by the manual sweep that raised the NestJS floors — that sweep
571
599
  asked about NestJS and never put the same question to the other ten peers.
572
600
 
573
- [Unreleased]: https://github.com/bymaxone/nest-realtime/compare/v1.2.2...HEAD
601
+ [Unreleased]: https://github.com/bymaxone/nest-realtime/compare/v1.2.3...HEAD
602
+ [1.2.3]: https://github.com/bymaxone/nest-realtime/compare/v1.2.2...v1.2.3
574
603
  [1.2.2]: https://github.com/bymaxone/nest-realtime/compare/v1.2.1...v1.2.2
575
604
  [1.2.1]: https://github.com/bymaxone/nest-realtime/compare/v1.2.0...v1.2.1
576
605
  [1.2.0]: https://github.com/bymaxone/nest-realtime/compare/v1.1.2...v1.2.0
package/README.md CHANGED
@@ -342,7 +342,7 @@ bootstrap()
342
342
  > [!IMPORTANT]
343
343
  > The `main.ts` line is not optional. `RealtimeIoAdapter` is what applies `websocket.cors`, `namespace`, `pingIntervalMs`, `pingTimeoutMs`, `maxHttpBufferSize` and `redisAdapter`. Without it those options are ignored, the gateway's own CORS stays closed (`origin: false`) so a browser on another origin cannot connect, and the module logs an error at start-up that names this fix.
344
344
 
345
- With `redisAdapter`, the adapter registers `@socket.io/redis-adapter` and calls `pubClient.duplicate()` for the subscriber; the library never opens its own Redis connection. Socket.IO's polling fallback needs sticky sessions even then — see [docs/architecture/scaling-cheatsheet.md](./docs/architecture/scaling-cheatsheet.md). On the frontend, a `ws://` or `wss://` `url` selects WebSocket in `RealtimeProvider`. Replay through `Last-Event-ID` and the offline queue are SSE features: a WebSocket connection has neither.
345
+ With `redisAdapter`, the adapter registers `@socket.io/redis-adapter` and calls `pubClient.duplicate()` for the subscriber; the library never opens its own Redis connection. If it cannot be installed (the package is missing, the client has no `duplicate()`), the boot fails with `REALTIME_REDIS_ADAPTER_FAILED` instead of serving a single instance; a Redis that is merely unreachable does not fail the boot. Socket.IO's polling fallback needs sticky sessions even then — see [docs/architecture/scaling-cheatsheet.md](./docs/architecture/scaling-cheatsheet.md). On the frontend, a `ws://` or `wss://` `url` selects WebSocket in `RealtimeProvider`. Replay through `Last-Event-ID` and the offline queue are SSE features: a WebSocket connection has neither.
346
346
 
347
347
  ---
348
348
 
@@ -830,6 +830,7 @@ These names belong to the library. Do not reuse them for application events. The
830
830
  | `REALTIME_TOO_MANY_CONNECTIONS` | Raised as the reason an evicted connection is closed |
831
831
  | `REALTIME_INVALID_TICKET` | Reserved, never raised today: a ticket store is yours to write |
832
832
  | `REALTIME_PUBSUB_UNAVAILABLE` | Reserved, never raised today: a pub/sub failure is logged |
833
+ | `REALTIME_REDIS_ADAPTER_FAILED` | Raised at bootstrap when the Redis adapter is configured and cannot be installed |
833
834
  | `REALTIME_PAYLOAD_TOO_LARGE` | Reserved, never raised today |
834
835
  | `REALTIME_REPLAY_BUFFER_MISS` | Reserved, never raised today |
835
836
 
@@ -28,6 +28,7 @@ var REALTIME_ERROR_CODES = {
28
28
  TOO_MANY_CONNECTIONS: "REALTIME_TOO_MANY_CONNECTIONS",
29
29
  INVALID_TICKET: "REALTIME_INVALID_TICKET",
30
30
  PUBSUB_UNAVAILABLE: "REALTIME_PUBSUB_UNAVAILABLE",
31
+ REDIS_ADAPTER_FAILED: "REALTIME_REDIS_ADAPTER_FAILED",
31
32
  PAYLOAD_TOO_LARGE: "REALTIME_PAYLOAD_TOO_LARGE",
32
33
  REPLAY_BUFFER_MISS: "REALTIME_REPLAY_BUFFER_MISS"
33
34
  };
@@ -1663,6 +1663,7 @@ declare const REALTIME_ERROR_CODES: {
1663
1663
  readonly TOO_MANY_CONNECTIONS: "REALTIME_TOO_MANY_CONNECTIONS";
1664
1664
  readonly INVALID_TICKET: "REALTIME_INVALID_TICKET";
1665
1665
  readonly PUBSUB_UNAVAILABLE: "REALTIME_PUBSUB_UNAVAILABLE";
1666
+ readonly REDIS_ADAPTER_FAILED: "REALTIME_REDIS_ADAPTER_FAILED";
1666
1667
  readonly PAYLOAD_TOO_LARGE: "REALTIME_PAYLOAD_TOO_LARGE";
1667
1668
  readonly REPLAY_BUFFER_MISS: "REALTIME_REPLAY_BUFFER_MISS";
1668
1669
  };
@@ -1663,6 +1663,7 @@ declare const REALTIME_ERROR_CODES: {
1663
1663
  readonly TOO_MANY_CONNECTIONS: "REALTIME_TOO_MANY_CONNECTIONS";
1664
1664
  readonly INVALID_TICKET: "REALTIME_INVALID_TICKET";
1665
1665
  readonly PUBSUB_UNAVAILABLE: "REALTIME_PUBSUB_UNAVAILABLE";
1666
+ readonly REDIS_ADAPTER_FAILED: "REALTIME_REDIS_ADAPTER_FAILED";
1666
1667
  readonly PAYLOAD_TOO_LARGE: "REALTIME_PAYLOAD_TOO_LARGE";
1667
1668
  readonly REPLAY_BUFFER_MISS: "REALTIME_REPLAY_BUFFER_MISS";
1668
1669
  };
@@ -26,6 +26,7 @@ var REALTIME_ERROR_CODES = {
26
26
  TOO_MANY_CONNECTIONS: "REALTIME_TOO_MANY_CONNECTIONS",
27
27
  INVALID_TICKET: "REALTIME_INVALID_TICKET",
28
28
  PUBSUB_UNAVAILABLE: "REALTIME_PUBSUB_UNAVAILABLE",
29
+ REDIS_ADAPTER_FAILED: "REALTIME_REDIS_ADAPTER_FAILED",
29
30
  PAYLOAD_TOO_LARGE: "REALTIME_PAYLOAD_TOO_LARGE",
30
31
  REPLAY_BUFFER_MISS: "REALTIME_REPLAY_BUFFER_MISS"
31
32
  };
@@ -30,6 +30,7 @@ var REALTIME_ERROR_CODES = {
30
30
  TOO_MANY_CONNECTIONS: "REALTIME_TOO_MANY_CONNECTIONS",
31
31
  INVALID_TICKET: "REALTIME_INVALID_TICKET",
32
32
  PUBSUB_UNAVAILABLE: "REALTIME_PUBSUB_UNAVAILABLE",
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"
35
36
  };
@@ -153,6 +153,7 @@ declare const REALTIME_ERROR_CODES: {
153
153
  readonly TOO_MANY_CONNECTIONS: "REALTIME_TOO_MANY_CONNECTIONS";
154
154
  readonly INVALID_TICKET: "REALTIME_INVALID_TICKET";
155
155
  readonly PUBSUB_UNAVAILABLE: "REALTIME_PUBSUB_UNAVAILABLE";
156
+ readonly REDIS_ADAPTER_FAILED: "REALTIME_REDIS_ADAPTER_FAILED";
156
157
  readonly PAYLOAD_TOO_LARGE: "REALTIME_PAYLOAD_TOO_LARGE";
157
158
  readonly REPLAY_BUFFER_MISS: "REALTIME_REPLAY_BUFFER_MISS";
158
159
  };
@@ -153,6 +153,7 @@ declare const REALTIME_ERROR_CODES: {
153
153
  readonly TOO_MANY_CONNECTIONS: "REALTIME_TOO_MANY_CONNECTIONS";
154
154
  readonly INVALID_TICKET: "REALTIME_INVALID_TICKET";
155
155
  readonly PUBSUB_UNAVAILABLE: "REALTIME_PUBSUB_UNAVAILABLE";
156
+ readonly REDIS_ADAPTER_FAILED: "REALTIME_REDIS_ADAPTER_FAILED";
156
157
  readonly PAYLOAD_TOO_LARGE: "REALTIME_PAYLOAD_TOO_LARGE";
157
158
  readonly REPLAY_BUFFER_MISS: "REALTIME_REPLAY_BUFFER_MISS";
158
159
  };
@@ -28,6 +28,7 @@ var REALTIME_ERROR_CODES = {
28
28
  TOO_MANY_CONNECTIONS: "REALTIME_TOO_MANY_CONNECTIONS",
29
29
  INVALID_TICKET: "REALTIME_INVALID_TICKET",
30
30
  PUBSUB_UNAVAILABLE: "REALTIME_PUBSUB_UNAVAILABLE",
31
+ REDIS_ADAPTER_FAILED: "REALTIME_REDIS_ADAPTER_FAILED",
31
32
  PAYLOAD_TOO_LARGE: "REALTIME_PAYLOAD_TOO_LARGE",
32
33
  REPLAY_BUFFER_MISS: "REALTIME_REPLAY_BUFFER_MISS"
33
34
  };
@@ -429,8 +429,7 @@ var RealtimeIoAdapter = class _RealtimeIoAdapter extends platformSocket_io.IoAda
429
429
  * Create the Socket.IO server with merged WebSocket options.
430
430
  *
431
431
  * When `websocket.redisAdapter.pubClient` is set, installs the
432
- * `@socket.io/redis-adapter` lazily (so the package stays an optional peer
433
- * dep — its absence does not crash the lib).
432
+ * `@socket.io/redis-adapter` lazily: the optional peer is needed only then.
434
433
  */
435
434
  createIOServer(port, opts) {
436
435
  const wsOpts = this.options.websocket ?? {};
@@ -443,17 +442,20 @@ var RealtimeIoAdapter = class _RealtimeIoAdapter extends platformSocket_io.IoAda
443
442
  };
444
443
  const server = super.createIOServer(port, mergedOpts);
445
444
  if (wsOpts.redisAdapter?.pubClient) {
446
- this.installRedisAdapter(server, wsOpts.redisAdapter.pubClient);
445
+ try {
446
+ this.installRedisAdapter(server, wsOpts.redisAdapter.pubClient);
447
+ } catch (err) {
448
+ server.close().catch(() => void 0);
449
+ throw err;
450
+ }
447
451
  }
448
452
  realtimeServers.add(server);
449
453
  return server;
450
454
  }
451
455
  /**
452
- * Lazily load and install `@socket.io/redis-adapter`.
453
- *
454
- * Uses a dynamic `require` so the package stays optional — absent peers do
455
- * not crash the lib. A load or install failure is logged and tolerated;
456
- * the lib degrades gracefully to single-instance mode.
456
+ * Install `@socket.io/redis-adapter`. A deterministic failure fails the boot: a
457
+ * silent single-instance server drops cross-node messages. An unreachable Redis
458
+ * is not one; reconnecting stays with the client.
457
459
  */
458
460
  installRedisAdapter(server, pubClient) {
459
461
  try {
@@ -461,14 +463,16 @@ var RealtimeIoAdapter = class _RealtimeIoAdapter extends platformSocket_io.IoAda
461
463
  const pub = pubClient;
462
464
  const sub = pub.duplicate();
463
465
  server.adapter(createAdapter(pub, sub));
464
- this.adapterLogger.log(
465
- "Socket.IO Redis adapter registered \u2014 cross-instance WebSocket fan-out enabled"
466
- );
467
466
  } catch (err) {
468
- this.adapterLogger.error(
469
- `Failed to register @socket.io/redis-adapter: ${err.message}. Falling back to single-instance mode.`
467
+ const reason = err instanceof Error ? err.message : String(err);
468
+ throw new Error(
469
+ `[${_RealtimeIoAdapter.name}] ${internal.REALTIME_ERROR_CODES.REDIS_ADAPTER_FAILED}: websocket.redisAdapter is set but the Socket.IO Redis adapter could not be installed (${reason}). Install @socket.io/redis-adapter and pass an ioredis client as pubClient.`,
470
+ { cause: err }
470
471
  );
471
472
  }
473
+ this.adapterLogger.log(
474
+ "Socket.IO Redis adapter registered \u2014 cross-instance WebSocket fan-out enabled"
475
+ );
472
476
  }
473
477
  };
474
478
 
@@ -598,7 +602,7 @@ exports.RealtimeGateway = class RealtimeGateway {
598
602
  }
599
603
  } catch (err) {
600
604
  this.logger.error(
601
- `handleConnection threw for socket ${socket.id} \u2014 disconnecting: ${err.message}`
605
+ `handleConnection threw for socket ${socket.id} \u2014 disconnecting: ${err instanceof Error ? err.message : String(err)}`
602
606
  );
603
607
  socket.disconnect(true);
604
608
  }
@@ -326,16 +326,13 @@ declare class RealtimeIoAdapter extends IoAdapter {
326
326
  * Create the Socket.IO server with merged WebSocket options.
327
327
  *
328
328
  * When `websocket.redisAdapter.pubClient` is set, installs the
329
- * `@socket.io/redis-adapter` lazily (so the package stays an optional peer
330
- * dep — its absence does not crash the lib).
329
+ * `@socket.io/redis-adapter` lazily: the optional peer is needed only then.
331
330
  */
332
331
  createIOServer(port: number, opts?: ServerOptions): unknown;
333
332
  /**
334
- * Lazily load and install `@socket.io/redis-adapter`.
335
- *
336
- * Uses a dynamic `require` so the package stays optional — absent peers do
337
- * not crash the lib. A load or install failure is logged and tolerated;
338
- * the lib degrades gracefully to single-instance mode.
333
+ * Install `@socket.io/redis-adapter`. A deterministic failure fails the boot: a
334
+ * silent single-instance server drops cross-node messages. An unreachable Redis
335
+ * is not one; reconnecting stays with the client.
339
336
  */
340
337
  private installRedisAdapter;
341
338
  }
@@ -326,16 +326,13 @@ declare class RealtimeIoAdapter extends IoAdapter {
326
326
  * Create the Socket.IO server with merged WebSocket options.
327
327
  *
328
328
  * When `websocket.redisAdapter.pubClient` is set, installs the
329
- * `@socket.io/redis-adapter` lazily (so the package stays an optional peer
330
- * dep — its absence does not crash the lib).
329
+ * `@socket.io/redis-adapter` lazily: the optional peer is needed only then.
331
330
  */
332
331
  createIOServer(port: number, opts?: ServerOptions): unknown;
333
332
  /**
334
- * Lazily load and install `@socket.io/redis-adapter`.
335
- *
336
- * Uses a dynamic `require` so the package stays optional — absent peers do
337
- * not crash the lib. A load or install failure is logged and tolerated;
338
- * the lib degrades gracefully to single-instance mode.
333
+ * Install `@socket.io/redis-adapter`. A deterministic failure fails the boot: a
334
+ * silent single-instance server drops cross-node messages. An unreachable Redis
335
+ * is not one; reconnecting stays with the client.
339
336
  */
340
337
  private installRedisAdapter;
341
338
  }
@@ -1,15 +1,17 @@
1
+ import { createRequire } from 'node:module';
1
2
  import { Injectable, Inject, Logger, Global, Module } from '@nestjs/common';
2
3
  import { ConnectionRegistry, RoomRegistry, REALTIME_AUTHENTICATOR_TOKEN, REALTIME_HOOKS_TOKEN, REALTIME_OPTIONS_TOKEN, SseTransport, ROOM_PREFIXES, REALTIME_ERROR_CODES, composeForRoot, composeForRootAsync, REALTIME_TRANSPORT_TOKEN, SseSubscriptionHandler, RealtimePubSubSubscriber, createSseController, resolveAuthTenant, assertIdentityIsNotBlank, parseCookieHeader, RESERVED_EVENT_NAMES } from '@bymax-one/nest-realtime/internal';
3
4
  import { WebSocketServer, WebSocketGateway } from '@nestjs/websockets';
4
5
  import { IoAdapter } from '@nestjs/platform-socket.io';
5
6
 
7
+ const require$1 = createRequire(import.meta.url || __filename);
6
8
  var __defProp = Object.defineProperty;
7
9
  var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
8
10
  var __defNormalProp = (obj, key, value) => key in obj ? __defProp(obj, key, { enumerable: true, configurable: true, writable: true, value }) : obj[key] = value;
9
- var __require = /* @__PURE__ */ ((x) => typeof require !== "undefined" ? require : typeof Proxy !== "undefined" ? new Proxy(x, {
10
- get: (a, b) => (typeof require !== "undefined" ? require : a)[b]
11
+ var __require = /* @__PURE__ */ ((x) => typeof require$1 !== "undefined" ? require$1 : typeof Proxy !== "undefined" ? new Proxy(x, {
12
+ get: (a, b) => (typeof require$1 !== "undefined" ? require$1 : a)[b]
11
13
  }) : x)(function(x) {
12
- if (typeof require !== "undefined") return require.apply(this, arguments);
14
+ if (typeof require$1 !== "undefined") return require$1.apply(this, arguments);
13
15
  throw Error('Dynamic require of "' + x + '" is not supported');
14
16
  });
15
17
  var __decorateClass = (decorators, target, key, kind) => {
@@ -427,8 +429,7 @@ var RealtimeIoAdapter = class _RealtimeIoAdapter extends IoAdapter {
427
429
  * Create the Socket.IO server with merged WebSocket options.
428
430
  *
429
431
  * When `websocket.redisAdapter.pubClient` is set, installs the
430
- * `@socket.io/redis-adapter` lazily (so the package stays an optional peer
431
- * dep — its absence does not crash the lib).
432
+ * `@socket.io/redis-adapter` lazily: the optional peer is needed only then.
432
433
  */
433
434
  createIOServer(port, opts) {
434
435
  const wsOpts = this.options.websocket ?? {};
@@ -441,17 +442,20 @@ var RealtimeIoAdapter = class _RealtimeIoAdapter extends IoAdapter {
441
442
  };
442
443
  const server = super.createIOServer(port, mergedOpts);
443
444
  if (wsOpts.redisAdapter?.pubClient) {
444
- this.installRedisAdapter(server, wsOpts.redisAdapter.pubClient);
445
+ try {
446
+ this.installRedisAdapter(server, wsOpts.redisAdapter.pubClient);
447
+ } catch (err) {
448
+ server.close().catch(() => void 0);
449
+ throw err;
450
+ }
445
451
  }
446
452
  realtimeServers.add(server);
447
453
  return server;
448
454
  }
449
455
  /**
450
- * Lazily load and install `@socket.io/redis-adapter`.
451
- *
452
- * Uses a dynamic `require` so the package stays optional — absent peers do
453
- * not crash the lib. A load or install failure is logged and tolerated;
454
- * the lib degrades gracefully to single-instance mode.
456
+ * Install `@socket.io/redis-adapter`. A deterministic failure fails the boot: a
457
+ * silent single-instance server drops cross-node messages. An unreachable Redis
458
+ * is not one; reconnecting stays with the client.
455
459
  */
456
460
  installRedisAdapter(server, pubClient) {
457
461
  try {
@@ -459,14 +463,16 @@ var RealtimeIoAdapter = class _RealtimeIoAdapter extends IoAdapter {
459
463
  const pub = pubClient;
460
464
  const sub = pub.duplicate();
461
465
  server.adapter(createAdapter(pub, sub));
462
- this.adapterLogger.log(
463
- "Socket.IO Redis adapter registered \u2014 cross-instance WebSocket fan-out enabled"
464
- );
465
466
  } catch (err) {
466
- this.adapterLogger.error(
467
- `Failed to register @socket.io/redis-adapter: ${err.message}. Falling back to single-instance mode.`
467
+ const reason = err instanceof Error ? err.message : String(err);
468
+ throw new Error(
469
+ `[${_RealtimeIoAdapter.name}] ${REALTIME_ERROR_CODES.REDIS_ADAPTER_FAILED}: websocket.redisAdapter is set but the Socket.IO Redis adapter could not be installed (${reason}). Install @socket.io/redis-adapter and pass an ioredis client as pubClient.`,
470
+ { cause: err }
468
471
  );
469
472
  }
473
+ this.adapterLogger.log(
474
+ "Socket.IO Redis adapter registered \u2014 cross-instance WebSocket fan-out enabled"
475
+ );
470
476
  }
471
477
  };
472
478
 
@@ -596,7 +602,7 @@ var RealtimeGateway = class {
596
602
  }
597
603
  } catch (err) {
598
604
  this.logger.error(
599
- `handleConnection threw for socket ${socket.id} \u2014 disconnecting: ${err.message}`
605
+ `handleConnection threw for socket ${socket.id} \u2014 disconnecting: ${err instanceof Error ? err.message : String(err)}`
600
606
  );
601
607
  socket.disconnect(true);
602
608
  }
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@bymax-one/nest-realtime",
3
- "version": "1.2.2",
3
+ "version": "1.2.3",
4
4
  "description": "Realtime backend → frontend communication for NestJS — dual-transport SSE (default) and WebSocket (opt-in) with a unified server-side API.",
5
5
  "author": "Bymax One <support@bymax.one>",
6
6
  "license": "MIT",