@bymax-one/nest-realtime 1.2.19 → 1.2.20

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,22 @@ Versioning is **not** strict [SemVer](https://semver.org/spec/v2.0.0.html) while
7
7
 
8
8
  ## [Unreleased]
9
9
 
10
+ ## [1.2.20] - 2026-11-20
11
+
12
+ ### Fixed
13
+
14
+ - **A getter or a proxy that throws, in an object the host hands over, is refused with the library's typed error.** A proxy or a getter returned as the options by a `useFactory` or by `createRealtimeOptions`, one on the provider `useExisting` names, and one as the `authenticator` raised the host's own error at registration; they now raise `REALTIME_INVALID_OPTIONS` with the error that was thrown as the `cause`. An `extraProviders` that is not an array of providers raised a raw `TypeError` or was accepted until the container reached it; it is now refused at registration, naming the entry.
15
+ - **An `onConnect` that fails under `onConnectFailure: 'close'` is no longer counted as a refused handshake on WebSocket.** The connection was admitted first, as on SSE, where nothing was counted; `bymax_realtime_connections_refused_total{reason="error"}` now means a handshake that failed with an unexpected error on both transports.
16
+ - **A `*_UNAVAILABLE` error no longer carries the text of the error underneath in its message.** The message names what could not be reached; the error that was thrown is the `cause`, as it already was. The `Subscribed to` line of `RedisRealtimePubSub` no longer names the channel.
17
+
18
+ #### Apply to a derived backend
19
+
20
+ Code that read the text of the underlying failure from the `message` of a `REALTIME_PUBSUB_UNAVAILABLE` or `REALTIME_TRANSPORT_UNAVAILABLE` error must read `error.cause` instead. A dashboard that summed `reason="error"` and counted WebSocket connections that `onConnect` closed will see those no longer counted. A log filter that matched `Subscribed to "<channel>"` matches `Subscribed to the realtime channel`.
21
+
22
+ ### Documentation
23
+
24
+ - **The README names `createRealtimeOptions` and `ConnectionAuthContext.userAgent`.**
25
+
10
26
  ## [1.2.19] - 2026-11-20
11
27
 
12
28
  ### Added
@@ -1203,7 +1219,8 @@ First published release.
1203
1219
  rather than by the manual sweep that raised the NestJS floors — that sweep
1204
1220
  asked about NestJS and never put the same question to the other ten peers.
1205
1221
 
1206
- [Unreleased]: https://github.com/bymaxone/nest-realtime/compare/v1.2.19...HEAD
1222
+ [Unreleased]: https://github.com/bymaxone/nest-realtime/compare/v1.2.20...HEAD
1223
+ [1.2.20]: https://github.com/bymaxone/nest-realtime/compare/v1.2.19...v1.2.20
1207
1224
  [1.2.19]: https://github.com/bymaxone/nest-realtime/compare/v1.2.18...v1.2.19
1208
1225
  [1.2.18]: https://github.com/bymaxone/nest-realtime/compare/v1.2.17...v1.2.18
1209
1226
  [1.2.17]: https://github.com/bymaxone/nest-realtime/compare/v1.2.16...v1.2.17
package/README.md CHANGED
@@ -412,7 +412,7 @@ An option that holds `undefined` or `null` is read as unset: it takes its defaul
412
412
 
413
413
  The shape of what you pass is checked at start-up too, and refused with `REALTIME_INVALID_OPTIONS`: `sse`, `websocket`, `reauthenticationPolicy` and `hooks` must be objects; `pubsub`, `offlineQueue` and `presence` must have every function of their interface (`IRealtimePubSub`, `IOfflineQueueStorage`, `IPresenceStorage`), on the object or its prototype; each hook that is set and `tenantResolver` must be a function; `sse.emitConnectionEvent` and `websocket.emitConnectionEvent` must be booleans; `sse.endpoint` must be a non-blank string, with or without a leading slash. An endpoint holds no whitespace, because no request can reach it, and the `sseEndpoint` of `forRootAsync` gets the same check. The options argument must be an object, and so must what a `forRootAsync` factory returns; an array, a `Date` or a `Map` is refused there and where a group is expected, while an instance of your own class is read by its keys. `new RedisOfflineQueue(options)` refuses options that are not an object and a `client` that is not one.
414
414
 
415
- The options are typed per entry point: `SseRealtimeModuleOptions` and `SseRealtimeModuleAsyncOptions` fix `transport: 'sse'`, and `WebSocketRealtimeModuleOptions` and `WebSocketRealtimeModuleAsyncOptions` (from `/websocket`) fix `'websocket' | 'both'`. `forRootAsync` takes `useFactory`, `useClass` (a `BymaxRealtimeModuleOptionsFactory`) or `useExisting`.
415
+ The options are typed per entry point: `SseRealtimeModuleOptions` and `SseRealtimeModuleAsyncOptions` fix `transport: 'sse'`, and `WebSocketRealtimeModuleOptions` and `WebSocketRealtimeModuleAsyncOptions` (from `/websocket`) fix `'websocket' | 'both'`. `forRootAsync` takes `useFactory`, `useClass` (a `BymaxRealtimeModuleOptionsFactory`) or `useExisting`. A `useClass` or `useExisting` provider implements `createRealtimeOptions()`, which returns the options or a promise of them; a provider that does not is refused with `REALTIME_INVALID_OPTIONS`, as is an `extraProviders` that is not an array of providers (a class, or an object with `provide`). An options object, a group, a pluggable piece or a provider whose read throws, such as a getter or a proxy, is refused the same way, with the error it threw as the `cause`.
416
416
 
417
417
  > [!IMPORTANT]
418
418
  > **`forRootAsync` takes the SSE route on the registration, not from the factory.** NestJS
@@ -500,7 +500,7 @@ export class ObservabilityModule {}
500
500
  | Metric | Type | Labels | Meaning |
501
501
  | ------------------------------------------ | ------- | ---------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------- |
502
502
  | `bymax_realtime_connections` | gauge | `transport` = `sse`, `websocket` | Connections open on this instance now. |
503
- | `bymax_realtime_connections_refused_total` | counter | `reason` = `limit`, `unauthorized`, `unavailable`, `error` | Handshakes refused since start; `error` is one that failed with an unexpected error (a 500). |
503
+ | `bymax_realtime_connections_refused_total` | counter | `reason` = `limit`, `unauthorized`, `unavailable`, `error` | Handshakes refused since start; `error` is one that failed with an unexpected error (a 500); a connection that `onConnectFailure: 'close'` closes was admitted first, and is not counted. |
504
504
  | `bymax_realtime_evictions_total` | counter | `reason` = `per_user_cap`, `slow_consumer`, `revoked` | Connections closed by the library or by a revocation. |
505
505
  | `bymax_realtime_events_emitted_total` | counter | `transport` = `sse`, `websocket` | Emit calls handled on this instance, not deliveries: a call with no recipient counts, and under `'both'` each transport counts it. |
506
506
  | `bymax_realtime_slow_consumer_drops_total` | counter | none | Connections cut for not reading what they were sent. |
@@ -857,6 +857,9 @@ proxy it is the proxy's address. Use it to decide whether a forwarded header suc
857
857
  `undefined` when the socket reports no address, and an IPv4 peer can arrive in its IPv4-mapped form
858
858
  (`::ffff:10.0.0.1`), which is passed through as reported.
859
859
 
860
+ `userAgent` is the raw `User-Agent` header, or `undefined` when the client sent none. Any client can
861
+ set it to anything, so it suits a log line and not a decision about who may connect.
862
+
860
863
  ### Rooms
861
864
 
862
865
  | Room ID | Used for | Auto-joined |
@@ -143,6 +143,30 @@ function applyDefaults(raw) {
143
143
  });
144
144
  }
145
145
 
146
+ // src/server/utils/realtime-error.ts
147
+ function realtimeError(code, detail, options = {}) {
148
+ const lead = options.who === void 0 ? code : `[${options.who}] ${code}`;
149
+ const message = `${lead}: ${detail}`;
150
+ const error = "cause" in options ? new Error(message, { cause: options.cause }) : new Error(message);
151
+ return Object.assign(error, { code });
152
+ }
153
+
154
+ // src/server/config/guard-host-reads.ts
155
+ var LIBRARY_CODES = new Set(Object.values(REALTIME_ERROR_CODES));
156
+ var isLibraryError = (error) => error instanceof Error && LIBRARY_CODES.has(error.code);
157
+ function guardHostReads(what, read) {
158
+ try {
159
+ return read();
160
+ } catch (error) {
161
+ if (isLibraryError(error)) throw error;
162
+ throw realtimeError(
163
+ REALTIME_ERROR_CODES.INVALID_OPTIONS,
164
+ `${what} could not be read: a getter or a proxy on it throws`,
165
+ { who: "BymaxRealtimeModule", cause: error }
166
+ );
167
+ }
168
+ }
169
+
146
170
  // src/server/constants/injection-tokens.constants.ts
147
171
  var REALTIME_OPTIONS_TOKEN = /* @__PURE__ */ Symbol("BYMAX_REALTIME_OPTIONS");
148
172
  var REALTIME_TRANSPORT_TOKEN = /* @__PURE__ */ Symbol("BYMAX_REALTIME_TRANSPORT");
@@ -176,14 +200,6 @@ function describeReceived(value) {
176
200
  return KIND_OF_TYPE[typeof value] ?? "an object";
177
201
  }
178
202
 
179
- // src/server/utils/realtime-error.ts
180
- function realtimeError(code, detail, options = {}) {
181
- const lead = options.who === void 0 ? code : `[${options.who}] ${code}`;
182
- const message = `${lead}: ${detail}`;
183
- const error = "cause" in options ? new Error(message, { cause: options.cause }) : new Error(message);
184
- return Object.assign(error, { code });
185
- }
186
-
187
203
  // src/server/utils/refuse-object.ts
188
204
  function refuseObject(who, path, value) {
189
205
  throw realtimeError(
@@ -261,10 +277,34 @@ function validateShapes(options) {
261
277
  assertBoolean("websocket.emitConnectionEvent", options.websocket?.emitConnectionEvent);
262
278
  assertSseEndpoint("sse.endpoint", options.sse?.endpoint);
263
279
  }
280
+ function assertExtraProviders(value) {
281
+ if (value === void 0 || value === null) return;
282
+ if (!Array.isArray(value)) {
283
+ throw realtimeError(
284
+ REALTIME_ERROR_CODES.INVALID_OPTIONS,
285
+ `extraProviders must be an array of providers, received ${describeReceived(value)}`,
286
+ { who: "BymaxRealtimeModule" }
287
+ );
288
+ }
289
+ value.forEach((entry, index) => {
290
+ const isClass = typeof entry === "function";
291
+ const hasProvide = isPlainObject(entry) && "provide" in entry;
292
+ if (isClass || hasProvide) return;
293
+ const received = isPlainObject(entry) && !Array.isArray(entry) ? "an object with no provide" : describeReceived(entry);
294
+ throw realtimeError(
295
+ REALTIME_ERROR_CODES.INVALID_OPTIONS,
296
+ `extraProviders[${index}] must be a provider (a class or an object with provide), received ${received}`,
297
+ { who: "BymaxRealtimeModule" }
298
+ );
299
+ });
300
+ }
264
301
 
265
302
  // src/server/config/validate-options.ts
266
303
  var VALID_TRANSPORTS = /* @__PURE__ */ new Set(["sse", "websocket", "both"]);
267
304
  function validateOptions(raw) {
305
+ guardHostReads("the options", () => validateReadOptions(raw));
306
+ }
307
+ function validateReadOptions(raw) {
268
308
  assertOptionsObject(raw);
269
309
  const options = dropUnset(raw);
270
310
  if (!options.transport || !VALID_TRANSPORTS.has(options.transport)) {
@@ -1175,7 +1215,7 @@ function composeRoomId(prefix, ...parts) {
1175
1215
  return [ROOM_PREFIXES[prefix], ...parts].join(":");
1176
1216
  }
1177
1217
  function unavailableError(code, who, what, cause) {
1178
- const { message } = realtimeError(code, `${what} (${describeError(cause)})`, { who });
1218
+ const { message } = realtimeError(code, what, { who });
1179
1219
  const error = Object.assign(new common.ServiceUnavailableException(), { code });
1180
1220
  Object.defineProperties(error, {
1181
1221
  message: { value: message, enumerable: false, writable: true, configurable: true },
@@ -2555,7 +2595,7 @@ function buildCommonProviders(resolved, instanceId) {
2555
2595
  }
2556
2596
  function composeForRoot(moduleClass, wiring, logger, raw) {
2557
2597
  assertOptionsObject(raw, moduleClass.name);
2558
- const options = dropUnset(raw);
2598
+ const options = guardHostReads("the options", () => dropUnset(raw));
2559
2599
  validateOptions(options);
2560
2600
  assertModeSupported(wiring, options.transport, moduleClass.name);
2561
2601
  const resolved = applyDefaults(options);
@@ -2593,7 +2633,7 @@ function resolveAsyncOptions(raw, declaredMode, instanceId, source, logger, modu
2593
2633
  throw realtimeError(REALTIME_ERROR_CODES.INVALID_OPTIONS, `${source} returned nothing`);
2594
2634
  }
2595
2635
  assertOptionsObject(raw, moduleName);
2596
- const options = dropUnset(raw);
2636
+ const options = guardHostReads("the options", () => dropUnset(raw));
2597
2637
  validateOptions(options);
2598
2638
  if (options.transport !== declaredMode) {
2599
2639
  throw realtimeError(
@@ -2633,14 +2673,18 @@ function buildOptionsProvider(asyncOptions, resolve, factoryToken) {
2633
2673
  return {
2634
2674
  provide: REALTIME_OPTIONS_TOKEN,
2635
2675
  useFactory: async (factory) => {
2636
- if (typeof factory?.createRealtimeOptions !== "function") {
2676
+ const create = guardHostReads(
2677
+ "the provider named by useExisting or useClass",
2678
+ () => factory?.createRealtimeOptions
2679
+ );
2680
+ if (typeof create !== "function") {
2637
2681
  throw realtimeError(
2638
2682
  REALTIME_ERROR_CODES.INVALID_OPTIONS,
2639
2683
  "the provider named by useExisting or useClass must implement createRealtimeOptions"
2640
2684
  );
2641
2685
  }
2642
2686
  return resolve(
2643
- await factory.createRealtimeOptions(),
2687
+ await create.call(factory),
2644
2688
  "createRealtimeOptions"
2645
2689
  );
2646
2690
  },
@@ -2684,6 +2728,7 @@ function composeForRootAsync(moduleClass, wiring, logger, asyncOptions) {
2684
2728
  assertModeSupported(wiring, asyncOptions.transport, moduleName);
2685
2729
  assertSseEndpoint("sseEndpoint", asyncOptions.sseEndpoint);
2686
2730
  assertSseEndpointApplies(asyncOptions, moduleName);
2731
+ assertExtraProviders(asyncOptions.extraProviders);
2687
2732
  const FACTORY_TOKEN = /* @__PURE__ */ Symbol("REALTIME_OPTIONS_FACTORY");
2688
2733
  const instanceId = crypto.randomUUID();
2689
2734
  const boundSseEndpoint = asyncOptions.sseEndpoint ?? DEFAULT_ASYNC_SSE_ENDPOINT;
@@ -2953,7 +2998,7 @@ var RedisRealtimePubSub = class _RedisRealtimePubSub {
2953
2998
  return unavailableError(
2954
2999
  REALTIME_ERROR_CODES.PUBSUB_UNAVAILABLE,
2955
3000
  _RedisRealtimePubSub.name,
2956
- `cannot publish to "${this.channel}"`,
3001
+ `cannot publish to "${this.channel}" (${reason})`,
2957
3002
  new Error(reason)
2958
3003
  );
2959
3004
  }
@@ -3070,7 +3115,7 @@ var RedisRealtimePubSub = class _RedisRealtimePubSub {
3070
3115
  this.#outageLogged = false;
3071
3116
  this.#lastRefusal = void 0;
3072
3117
  this.logger.log(
3073
- `Subscribed to "${this.channel}"; remote events and revocations reach this instance`
3118
+ `Subscribed to the realtime channel; remote events and revocations reach this instance`
3074
3119
  );
3075
3120
  }
3076
3121
  markDown(wording, error) {
@@ -2374,7 +2374,8 @@ type UnavailableError = ServiceUnavailableException & {
2374
2374
  /**
2375
2375
  * Builds the rejection for a call whose effect did not happen, such as a revocation that never
2376
2376
  * reached its connection. The stable code leads the message, as it does in the other errors this
2377
- * library raises, is also the `code` property, and the original failure travels as `cause`.
2377
+ * library raises, is also the `code` property, and the original failure travels as `cause` alone: its
2378
+ * text, which is a driver's or a host's, is not in the message.
2378
2379
  *
2379
2380
  * It is Nest's `ServiceUnavailableException`, so a consumer's controller that lets it escape
2380
2381
  * answers 503 with the generic body, and the library's own text never reaches a client: the
@@ -2374,7 +2374,8 @@ type UnavailableError = ServiceUnavailableException & {
2374
2374
  /**
2375
2375
  * Builds the rejection for a call whose effect did not happen, such as a revocation that never
2376
2376
  * reached its connection. The stable code leads the message, as it does in the other errors this
2377
- * library raises, is also the `code` property, and the original failure travels as `cause`.
2377
+ * library raises, is also the `code` property, and the original failure travels as `cause` alone: its
2378
+ * text, which is a driver's or a host's, is not in the message.
2378
2379
  *
2379
2380
  * It is Nest's `ServiceUnavailableException`, so a consumer's controller that lets it escape
2380
2381
  * answers 503 with the generic body, and the library's own text never reaches a client: the
@@ -141,6 +141,30 @@ function applyDefaults(raw) {
141
141
  });
142
142
  }
143
143
 
144
+ // src/server/utils/realtime-error.ts
145
+ function realtimeError(code, detail, options = {}) {
146
+ const lead = options.who === void 0 ? code : `[${options.who}] ${code}`;
147
+ const message = `${lead}: ${detail}`;
148
+ const error = "cause" in options ? new Error(message, { cause: options.cause }) : new Error(message);
149
+ return Object.assign(error, { code });
150
+ }
151
+
152
+ // src/server/config/guard-host-reads.ts
153
+ var LIBRARY_CODES = new Set(Object.values(REALTIME_ERROR_CODES));
154
+ var isLibraryError = (error) => error instanceof Error && LIBRARY_CODES.has(error.code);
155
+ function guardHostReads(what, read) {
156
+ try {
157
+ return read();
158
+ } catch (error) {
159
+ if (isLibraryError(error)) throw error;
160
+ throw realtimeError(
161
+ REALTIME_ERROR_CODES.INVALID_OPTIONS,
162
+ `${what} could not be read: a getter or a proxy on it throws`,
163
+ { who: "BymaxRealtimeModule", cause: error }
164
+ );
165
+ }
166
+ }
167
+
144
168
  // src/server/constants/injection-tokens.constants.ts
145
169
  var REALTIME_OPTIONS_TOKEN = /* @__PURE__ */ Symbol("BYMAX_REALTIME_OPTIONS");
146
170
  var REALTIME_TRANSPORT_TOKEN = /* @__PURE__ */ Symbol("BYMAX_REALTIME_TRANSPORT");
@@ -174,14 +198,6 @@ function describeReceived(value) {
174
198
  return KIND_OF_TYPE[typeof value] ?? "an object";
175
199
  }
176
200
 
177
- // src/server/utils/realtime-error.ts
178
- function realtimeError(code, detail, options = {}) {
179
- const lead = options.who === void 0 ? code : `[${options.who}] ${code}`;
180
- const message = `${lead}: ${detail}`;
181
- const error = "cause" in options ? new Error(message, { cause: options.cause }) : new Error(message);
182
- return Object.assign(error, { code });
183
- }
184
-
185
201
  // src/server/utils/refuse-object.ts
186
202
  function refuseObject(who, path, value) {
187
203
  throw realtimeError(
@@ -259,10 +275,34 @@ function validateShapes(options) {
259
275
  assertBoolean("websocket.emitConnectionEvent", options.websocket?.emitConnectionEvent);
260
276
  assertSseEndpoint("sse.endpoint", options.sse?.endpoint);
261
277
  }
278
+ function assertExtraProviders(value) {
279
+ if (value === void 0 || value === null) return;
280
+ if (!Array.isArray(value)) {
281
+ throw realtimeError(
282
+ REALTIME_ERROR_CODES.INVALID_OPTIONS,
283
+ `extraProviders must be an array of providers, received ${describeReceived(value)}`,
284
+ { who: "BymaxRealtimeModule" }
285
+ );
286
+ }
287
+ value.forEach((entry, index) => {
288
+ const isClass = typeof entry === "function";
289
+ const hasProvide = isPlainObject(entry) && "provide" in entry;
290
+ if (isClass || hasProvide) return;
291
+ const received = isPlainObject(entry) && !Array.isArray(entry) ? "an object with no provide" : describeReceived(entry);
292
+ throw realtimeError(
293
+ REALTIME_ERROR_CODES.INVALID_OPTIONS,
294
+ `extraProviders[${index}] must be a provider (a class or an object with provide), received ${received}`,
295
+ { who: "BymaxRealtimeModule" }
296
+ );
297
+ });
298
+ }
262
299
 
263
300
  // src/server/config/validate-options.ts
264
301
  var VALID_TRANSPORTS = /* @__PURE__ */ new Set(["sse", "websocket", "both"]);
265
302
  function validateOptions(raw) {
303
+ guardHostReads("the options", () => validateReadOptions(raw));
304
+ }
305
+ function validateReadOptions(raw) {
266
306
  assertOptionsObject(raw);
267
307
  const options = dropUnset(raw);
268
308
  if (!options.transport || !VALID_TRANSPORTS.has(options.transport)) {
@@ -1173,7 +1213,7 @@ function composeRoomId(prefix, ...parts) {
1173
1213
  return [ROOM_PREFIXES[prefix], ...parts].join(":");
1174
1214
  }
1175
1215
  function unavailableError(code, who, what, cause) {
1176
- const { message } = realtimeError(code, `${what} (${describeError(cause)})`, { who });
1216
+ const { message } = realtimeError(code, what, { who });
1177
1217
  const error = Object.assign(new ServiceUnavailableException(), { code });
1178
1218
  Object.defineProperties(error, {
1179
1219
  message: { value: message, enumerable: false, writable: true, configurable: true },
@@ -2553,7 +2593,7 @@ function buildCommonProviders(resolved, instanceId) {
2553
2593
  }
2554
2594
  function composeForRoot(moduleClass, wiring, logger, raw) {
2555
2595
  assertOptionsObject(raw, moduleClass.name);
2556
- const options = dropUnset(raw);
2596
+ const options = guardHostReads("the options", () => dropUnset(raw));
2557
2597
  validateOptions(options);
2558
2598
  assertModeSupported(wiring, options.transport, moduleClass.name);
2559
2599
  const resolved = applyDefaults(options);
@@ -2591,7 +2631,7 @@ function resolveAsyncOptions(raw, declaredMode, instanceId, source, logger, modu
2591
2631
  throw realtimeError(REALTIME_ERROR_CODES.INVALID_OPTIONS, `${source} returned nothing`);
2592
2632
  }
2593
2633
  assertOptionsObject(raw, moduleName);
2594
- const options = dropUnset(raw);
2634
+ const options = guardHostReads("the options", () => dropUnset(raw));
2595
2635
  validateOptions(options);
2596
2636
  if (options.transport !== declaredMode) {
2597
2637
  throw realtimeError(
@@ -2631,14 +2671,18 @@ function buildOptionsProvider(asyncOptions, resolve, factoryToken) {
2631
2671
  return {
2632
2672
  provide: REALTIME_OPTIONS_TOKEN,
2633
2673
  useFactory: async (factory) => {
2634
- if (typeof factory?.createRealtimeOptions !== "function") {
2674
+ const create = guardHostReads(
2675
+ "the provider named by useExisting or useClass",
2676
+ () => factory?.createRealtimeOptions
2677
+ );
2678
+ if (typeof create !== "function") {
2635
2679
  throw realtimeError(
2636
2680
  REALTIME_ERROR_CODES.INVALID_OPTIONS,
2637
2681
  "the provider named by useExisting or useClass must implement createRealtimeOptions"
2638
2682
  );
2639
2683
  }
2640
2684
  return resolve(
2641
- await factory.createRealtimeOptions(),
2685
+ await create.call(factory),
2642
2686
  "createRealtimeOptions"
2643
2687
  );
2644
2688
  },
@@ -2682,6 +2726,7 @@ function composeForRootAsync(moduleClass, wiring, logger, asyncOptions) {
2682
2726
  assertModeSupported(wiring, asyncOptions.transport, moduleName);
2683
2727
  assertSseEndpoint("sseEndpoint", asyncOptions.sseEndpoint);
2684
2728
  assertSseEndpointApplies(asyncOptions, moduleName);
2729
+ assertExtraProviders(asyncOptions.extraProviders);
2685
2730
  const FACTORY_TOKEN = /* @__PURE__ */ Symbol("REALTIME_OPTIONS_FACTORY");
2686
2731
  const instanceId = randomUUID();
2687
2732
  const boundSseEndpoint = asyncOptions.sseEndpoint ?? DEFAULT_ASYNC_SSE_ENDPOINT;
@@ -2951,7 +2996,7 @@ var RedisRealtimePubSub = class _RedisRealtimePubSub {
2951
2996
  return unavailableError(
2952
2997
  REALTIME_ERROR_CODES.PUBSUB_UNAVAILABLE,
2953
2998
  _RedisRealtimePubSub.name,
2954
- `cannot publish to "${this.channel}"`,
2999
+ `cannot publish to "${this.channel}" (${reason})`,
2955
3000
  new Error(reason)
2956
3001
  );
2957
3002
  }
@@ -3068,7 +3113,7 @@ var RedisRealtimePubSub = class _RedisRealtimePubSub {
3068
3113
  this.#outageLogged = false;
3069
3114
  this.#lastRefusal = void 0;
3070
3115
  this.logger.log(
3071
- `Subscribed to "${this.channel}"; remote events and revocations reach this instance`
3116
+ `Subscribed to the realtime channel; remote events and revocations reach this instance`
3072
3117
  );
3073
3118
  }
3074
3119
  markDown(wording, error) {
@@ -31,6 +31,16 @@ var __accessCheck = (obj, member, msg) => member.has(obj) || __typeError("Cannot
31
31
  var __privateGet = (obj, member, getter) => (__accessCheck(obj, member, "read from private field"), getter ? getter.call(obj) : member.get(obj));
32
32
  var __privateAdd = (obj, member, value) => member.has(obj) ? __typeError("Cannot add the same private member more than once") : member instanceof WeakSet ? member.add(obj) : member.set(obj, value);
33
33
  var __privateSet = (obj, member, value, setter) => (__accessCheck(obj, member, "write to private field"), member.set(obj, value), value);
34
+
35
+ // src/websocket/transports/websocket/connect-hook-failure.ts
36
+ var ConnectHookFailure = class extends Error {
37
+ constructor(cause) {
38
+ super("onConnect hook failed", { cause });
39
+ this.name = "ConnectHookFailure";
40
+ }
41
+ };
42
+
43
+ // src/websocket/transports/websocket/websocket.transport.ts
34
44
  var CONNECTION_ROOM_PREFIX = "connection";
35
45
  var DEFAULT_MAX_CONNECTIONS_PER_USER = 5;
36
46
  var _shuttingDown;
@@ -116,7 +126,7 @@ exports.WebSocketTransport = class WebSocketTransport {
116
126
  const failed = await this.runOnConnect(socket, auth, connectedAt);
117
127
  if (!failed) return;
118
128
  if (this.options.onConnectFailure === "close") {
119
- throw new Error("onConnect hook failed", { cause: failed.error });
129
+ throw new ConnectHookFailure(failed.error);
120
130
  }
121
131
  internal.logEvent(
122
132
  this.logger,
@@ -225,7 +235,7 @@ exports.WebSocketTransport = class WebSocketTransport {
225
235
  throw internal.unavailableError(
226
236
  internal.REALTIME_ERROR_CODES.TRANSPORT_UNAVAILABLE,
227
237
  exports.WebSocketTransport.name,
228
- `the WebSocket server is not attached, so ${connectionId} cannot be revoked`,
238
+ `the WebSocket server is not attached, so ${connectionId} cannot be revoked (server not attached)`,
229
239
  new Error("server not attached")
230
240
  );
231
241
  }
@@ -622,7 +632,7 @@ exports.RealtimeGateway = class RealtimeGateway {
622
632
  } else if (err instanceof internal.AuthenticationUnavailableError) {
623
633
  this.tally?.refused("unavailable");
624
634
  } else {
625
- this.tally?.refused("error");
635
+ if (!(err instanceof ConnectHookFailure)) this.tally?.refused("error");
626
636
  internal.logEvent(
627
637
  this.logger,
628
638
  "error",
@@ -31,6 +31,16 @@ var __accessCheck = (obj, member, msg) => member.has(obj) || __typeError("Cannot
31
31
  var __privateGet = (obj, member, getter) => (__accessCheck(obj, member, "read from private field"), getter ? getter.call(obj) : member.get(obj));
32
32
  var __privateAdd = (obj, member, value) => member.has(obj) ? __typeError("Cannot add the same private member more than once") : member instanceof WeakSet ? member.add(obj) : member.set(obj, value);
33
33
  var __privateSet = (obj, member, value, setter) => (__accessCheck(obj, member, "write to private field"), member.set(obj, value), value);
34
+
35
+ // src/websocket/transports/websocket/connect-hook-failure.ts
36
+ var ConnectHookFailure = class extends Error {
37
+ constructor(cause) {
38
+ super("onConnect hook failed", { cause });
39
+ this.name = "ConnectHookFailure";
40
+ }
41
+ };
42
+
43
+ // src/websocket/transports/websocket/websocket.transport.ts
34
44
  var CONNECTION_ROOM_PREFIX = "connection";
35
45
  var DEFAULT_MAX_CONNECTIONS_PER_USER = 5;
36
46
  var _shuttingDown;
@@ -116,7 +126,7 @@ var WebSocketTransport = class {
116
126
  const failed = await this.runOnConnect(socket, auth, connectedAt);
117
127
  if (!failed) return;
118
128
  if (this.options.onConnectFailure === "close") {
119
- throw new Error("onConnect hook failed", { cause: failed.error });
129
+ throw new ConnectHookFailure(failed.error);
120
130
  }
121
131
  logEvent(
122
132
  this.logger,
@@ -225,7 +235,7 @@ var WebSocketTransport = class {
225
235
  throw unavailableError(
226
236
  REALTIME_ERROR_CODES.TRANSPORT_UNAVAILABLE,
227
237
  WebSocketTransport.name,
228
- `the WebSocket server is not attached, so ${connectionId} cannot be revoked`,
238
+ `the WebSocket server is not attached, so ${connectionId} cannot be revoked (server not attached)`,
229
239
  new Error("server not attached")
230
240
  );
231
241
  }
@@ -622,7 +632,7 @@ var RealtimeGateway = class {
622
632
  } else if (err instanceof AuthenticationUnavailableError) {
623
633
  this.tally?.refused("unavailable");
624
634
  } else {
625
- this.tally?.refused("error");
635
+ if (!(err instanceof ConnectHookFailure)) this.tally?.refused("error");
626
636
  logEvent(
627
637
  this.logger,
628
638
  "error",
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@bymax-one/nest-realtime",
3
- "version": "1.2.19",
3
+ "version": "1.2.20",
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",