@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.
@@ -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
+ TRANSPORT_UNAVAILABLE: "REALTIME_TRANSPORT_UNAVAILABLE",
33
34
  REDIS_ADAPTER_FAILED: "REALTIME_REDIS_ADAPTER_FAILED",
34
35
  PAYLOAD_TOO_LARGE: "REALTIME_PAYLOAD_TOO_LARGE",
35
36
  REPLAY_BUFFER_MISS: "REALTIME_REPLAY_BUFFER_MISS"
@@ -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 TRANSPORT_UNAVAILABLE: "REALTIME_TRANSPORT_UNAVAILABLE";
156
157
  readonly REDIS_ADAPTER_FAILED: "REALTIME_REDIS_ADAPTER_FAILED";
157
158
  readonly PAYLOAD_TOO_LARGE: "REALTIME_PAYLOAD_TOO_LARGE";
158
159
  readonly REPLAY_BUFFER_MISS: "REALTIME_REPLAY_BUFFER_MISS";
@@ -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 TRANSPORT_UNAVAILABLE: "REALTIME_TRANSPORT_UNAVAILABLE";
156
157
  readonly REDIS_ADAPTER_FAILED: "REALTIME_REDIS_ADAPTER_FAILED";
157
158
  readonly PAYLOAD_TOO_LARGE: "REALTIME_PAYLOAD_TOO_LARGE";
158
159
  readonly REPLAY_BUFFER_MISS: "REALTIME_REPLAY_BUFFER_MISS";
@@ -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
+ TRANSPORT_UNAVAILABLE: "REALTIME_TRANSPORT_UNAVAILABLE",
31
32
  REDIS_ADAPTER_FAILED: "REALTIME_REDIS_ADAPTER_FAILED",
32
33
  PAYLOAD_TOO_LARGE: "REALTIME_PAYLOAD_TOO_LARGE",
33
34
  REPLAY_BUFFER_MISS: "REALTIME_REPLAY_BUFFER_MISS"
@@ -42,11 +42,12 @@ exports.WebSocketTransport = class WebSocketTransport {
42
42
  logger = new common.Logger(exports.WebSocketTransport.name);
43
43
  /** Nullable until the gateway's afterInit wires the instance. */
44
44
  server = null;
45
+ warnedUnattached = false;
45
46
  /**
46
47
  * Wire the Socket.IO server. Called by `RealtimeGateway.afterInit`.
47
48
  *
48
- * All emit methods silently no-op until this is called, so the transport is
49
- * safe to construct before the HTTP server is ready.
49
+ * Until this is called an emit delivers nothing and still resolves, with one warning for
50
+ * the first, so the transport is safe to construct before the HTTP server is ready.
50
51
  *
51
52
  * @param server - The live Socket.IO `Server` instance from the NestJS gateway.
52
53
  */
@@ -54,6 +55,19 @@ exports.WebSocketTransport = class WebSocketTransport {
54
55
  this.server = server;
55
56
  this.logger.log("Socket.IO server wired to WebSocketTransport");
56
57
  }
58
+ /**
59
+ * The attached server, or `null` before the gateway attaches one. An emit made before
60
+ * then delivers nothing and still resolves; that is logged once, not once per emit.
61
+ */
62
+ attached(op) {
63
+ if (!this.server && !this.warnedUnattached) {
64
+ this.warnedUnattached = true;
65
+ this.logger.warn(
66
+ `${internal.REALTIME_ERROR_CODES.TRANSPORT_UNAVAILABLE} op=${op}: no WebSocket server is attached yet, so emits are dropped until the gateway initialises`
67
+ );
68
+ }
69
+ return this.server;
70
+ }
57
71
  /**
58
72
  * Resolve the map of locally-connected sockets, tolerating both server shapes.
59
73
  *
@@ -168,7 +182,7 @@ exports.WebSocketTransport = class WebSocketTransport {
168
182
  * @param data - Payload forwarded to all matching connections.
169
183
  */
170
184
  async emitToUser(userId, event, data) {
171
- this.server?.to(`${internal.ROOM_PREFIXES.USER}:${userId}`).emit(event, data);
185
+ this.attached("emitToUser")?.to(`${internal.ROOM_PREFIXES.USER}:${userId}`).emit(event, data);
172
186
  }
173
187
  /**
174
188
  * Send an event to every connection within a tenant (uses `tenant:{tenantId}` room).
@@ -178,7 +192,7 @@ exports.WebSocketTransport = class WebSocketTransport {
178
192
  * @param data - Payload forwarded to all matching connections.
179
193
  */
180
194
  async emitToTenant(tenantId, event, data) {
181
- this.server?.to(`${internal.ROOM_PREFIXES.TENANT}:${tenantId}`).emit(event, data);
195
+ this.attached("emitToTenant")?.to(`${internal.ROOM_PREFIXES.TENANT}:${tenantId}`).emit(event, data);
182
196
  }
183
197
  /**
184
198
  * Send an event to every connection in an arbitrary room.
@@ -188,7 +202,7 @@ exports.WebSocketTransport = class WebSocketTransport {
188
202
  * @param data - Payload forwarded to all connections in the room.
189
203
  */
190
204
  async emitToRoom(roomId, event, data) {
191
- this.server?.to(roomId).emit(event, data);
205
+ this.attached("emitToRoom")?.to(roomId).emit(event, data);
192
206
  }
193
207
  /**
194
208
  * Broadcast an event to all connected clients.
@@ -197,7 +211,7 @@ exports.WebSocketTransport = class WebSocketTransport {
197
211
  * @param data - Payload forwarded to every connected socket.
198
212
  */
199
213
  async broadcast(event, data) {
200
- this.server?.emit(event, data);
214
+ this.attached("broadcast")?.emit(event, data);
201
215
  }
202
216
  /**
203
217
  * Join a connection to an additional room (updates both Socket.IO and `RoomRegistry`).
@@ -237,13 +251,31 @@ exports.WebSocketTransport = class WebSocketTransport {
237
251
  *
238
252
  * @param connectionId - The socket `id` of the connection to disconnect.
239
253
  * @param _reason - Optional reason string (unused at the Socket.IO level; passed to `unregisterSocket`).
254
+ * @throws {Error} `REALTIME_TRANSPORT_UNAVAILABLE` when no server is attached or the
255
+ * fan-out throws: the revocation did not leave this node.
240
256
  */
241
257
  async disconnect(connectionId, _reason) {
242
258
  const server = this.server;
243
- if (!server) return;
244
- const local = this.localSockets()?.get(connectionId);
245
- if (local) local.disconnect(true);
246
- server.in(`${CONNECTION_ROOM_PREFIX}:${connectionId}`).disconnectSockets(true);
259
+ if (!server) {
260
+ throw internal.unavailableError(
261
+ internal.REALTIME_ERROR_CODES.TRANSPORT_UNAVAILABLE,
262
+ exports.WebSocketTransport.name,
263
+ `the WebSocket server is not attached, so ${connectionId} cannot be revoked`,
264
+ new Error("server not attached")
265
+ );
266
+ }
267
+ try {
268
+ const local = this.localSockets()?.get(connectionId);
269
+ if (local) local.disconnect(true);
270
+ server.in(`${CONNECTION_ROOM_PREFIX}:${connectionId}`).disconnectSockets(true);
271
+ } catch (error) {
272
+ throw internal.unavailableError(
273
+ internal.REALTIME_ERROR_CODES.TRANSPORT_UNAVAILABLE,
274
+ exports.WebSocketTransport.name,
275
+ `the revocation of ${connectionId} could not be sent`,
276
+ error
277
+ );
278
+ }
247
279
  }
248
280
  /**
249
281
  * Evict the user's oldest WebSocket connections (FIFO) when over
@@ -339,38 +371,58 @@ exports.CompositeTransport = class CompositeTransport {
339
371
  /**
340
372
  * Join a connection to a room.
341
373
  *
342
- * Both transports are attempted; only the one that owns the connection
343
- * succeeds. The other's failure is expected and swallowed.
374
+ * Both transports are asked; the one that holds the connection acts. Rejects with the
375
+ * failure of whichever transport failed.
344
376
  */
345
377
  async joinRoom(connectionId, roomId) {
346
- await Promise.all([
347
- this.sse.joinRoom(connectionId, roomId).catch(() => void 0),
348
- this.ws.joinRoom(connectionId, roomId).catch(() => void 0)
378
+ await this.settleBoth("joinRoom", connectionId, [
379
+ () => this.sse.joinRoom(connectionId, roomId),
380
+ () => this.ws.joinRoom(connectionId, roomId)
349
381
  ]);
350
382
  }
351
383
  /**
352
384
  * Remove a connection from a room.
353
385
  *
354
- * Both transports are attempted tolerantly — one will succeed, the other
355
- * may fail silently.
386
+ * Both transports are asked; the one that holds the connection acts. Rejects with the
387
+ * failure of whichever transport failed: a client left in a room it was removed from keeps
388
+ * receiving that room's events.
356
389
  */
357
390
  async leaveRoom(connectionId, roomId) {
358
- await Promise.all([
359
- this.sse.leaveRoom(connectionId, roomId).catch(() => void 0),
360
- this.ws.leaveRoom(connectionId, roomId).catch(() => void 0)
391
+ await this.settleBoth("leaveRoom", connectionId, [
392
+ () => this.sse.leaveRoom(connectionId, roomId),
393
+ () => this.ws.leaveRoom(connectionId, roomId)
361
394
  ]);
362
395
  }
363
396
  /**
364
397
  * Disconnect a specific connection.
365
398
  *
366
- * Both transports are attempted; the one owning the connection disconnects it.
399
+ * Both transports are asked; the one that holds the connection disconnects it. Rejects when
400
+ * either one could not: the revocation has not reached the connection.
367
401
  */
368
402
  async disconnect(connectionId, reason) {
369
- await Promise.all([
370
- this.sse.disconnect(connectionId, reason).catch(() => void 0),
371
- this.ws.disconnect(connectionId, reason).catch(() => void 0)
403
+ await this.settleBoth("disconnect", connectionId, [
404
+ () => this.sse.disconnect(connectionId, reason),
405
+ () => this.ws.disconnect(connectionId, reason)
372
406
  ]);
373
407
  }
408
+ /**
409
+ * Run a per-connection operation on both transports and reject if either failed.
410
+ *
411
+ * One failure is rethrown as it is; both are reported together under
412
+ * `REALTIME_TRANSPORT_UNAVAILABLE`, with every reason in `cause`.
413
+ */
414
+ async settleBoth(op, connectionId, tasks) {
415
+ const results = await Promise.allSettled(tasks.map((t) => t()));
416
+ const reasons = results.flatMap((r) => r.status === "rejected" ? [r.reason] : []);
417
+ if (reasons.length === 0) return;
418
+ if (reasons.length === 1) throw reasons[0];
419
+ throw internal.unavailableError(
420
+ internal.REALTIME_ERROR_CODES.TRANSPORT_UNAVAILABLE,
421
+ exports.CompositeTransport.name,
422
+ `${op} of ${connectionId} failed on both transports`,
423
+ new AggregateError(reasons, reasons.map(internal.describeError).join("; "))
424
+ );
425
+ }
374
426
  /**
375
427
  * Run two transport tasks in parallel via `Promise.allSettled`.
376
428
  *
@@ -81,16 +81,22 @@ declare class WebSocketTransport implements ITransport {
81
81
  private readonly logger;
82
82
  /** Nullable until the gateway's afterInit wires the instance. */
83
83
  private server;
84
+ private warnedUnattached;
84
85
  constructor(connections: ConnectionRegistry, rooms: RoomRegistry, auth: IConnectionAuthenticator, hooks: IConnectionLifecycleHooks, options: BymaxRealtimeModuleOptions);
85
86
  /**
86
87
  * Wire the Socket.IO server. Called by `RealtimeGateway.afterInit`.
87
88
  *
88
- * All emit methods silently no-op until this is called, so the transport is
89
- * safe to construct before the HTTP server is ready.
89
+ * Until this is called an emit delivers nothing and still resolves, with one warning for
90
+ * the first, so the transport is safe to construct before the HTTP server is ready.
90
91
  *
91
92
  * @param server - The live Socket.IO `Server` instance from the NestJS gateway.
92
93
  */
93
94
  setServer(server: Server): void;
95
+ /**
96
+ * The attached server, or `null` before the gateway attaches one. An emit made before
97
+ * then delivers nothing and still resolves; that is logged once, not once per emit.
98
+ */
99
+ private attached;
94
100
  /**
95
101
  * Resolve the map of locally-connected sockets, tolerating both server shapes.
96
102
  *
@@ -193,6 +199,8 @@ declare class WebSocketTransport implements ITransport {
193
199
  *
194
200
  * @param connectionId - The socket `id` of the connection to disconnect.
195
201
  * @param _reason - Optional reason string (unused at the Socket.IO level; passed to `unregisterSocket`).
202
+ * @throws {Error} `REALTIME_TRANSPORT_UNAVAILABLE` when no server is attached or the
203
+ * fan-out throws: the revocation did not leave this node.
196
204
  */
197
205
  disconnect(connectionId: string, _reason?: string): Promise<void>;
198
206
  /**
@@ -344,10 +352,12 @@ declare class RealtimeIoAdapter extends IoAdapter {
344
352
  * parallel via `Promise.allSettled` so a failure in one never aborts the other.
345
353
  * Failures are logged as warnings without rethrowing.
346
354
  *
347
- * `joinRoom`, `leaveRoom`, and `disconnect` attempt both transports tolerantly:
348
- * only the transport that owns the connection will succeed; the other's rejection
349
- * is swallowed. There is no double-delivery because each connection lives on
350
- * exactly one transport.
355
+ * `joinRoom`, `leaveRoom`, and `disconnect` ask both transports and settle both: each
356
+ * transport acts only on a connection it holds, and a connection neither holds is handed
357
+ * to the bus (SSE) and the adapter (WebSocket) for the instance that does. A failure of
358
+ * either one rejects the call, because a revocation or a room change that did not happen
359
+ * must not be reported as done. There is no double-delivery because each connection lives
360
+ * on exactly one transport.
351
361
  *
352
362
  * `kind` reports `'sse'` (the dominant transport); `ITransport.kind` is
353
363
  * `'sse' | 'websocket'` — `'both'` is a module-level `TransportMode`, not a
@@ -393,23 +403,32 @@ declare class CompositeTransport implements ITransport {
393
403
  /**
394
404
  * Join a connection to a room.
395
405
  *
396
- * Both transports are attempted; only the one that owns the connection
397
- * succeeds. The other's failure is expected and swallowed.
406
+ * Both transports are asked; the one that holds the connection acts. Rejects with the
407
+ * failure of whichever transport failed.
398
408
  */
399
409
  joinRoom(connectionId: string, roomId: string): Promise<void>;
400
410
  /**
401
411
  * Remove a connection from a room.
402
412
  *
403
- * Both transports are attempted tolerantly — one will succeed, the other
404
- * may fail silently.
413
+ * Both transports are asked; the one that holds the connection acts. Rejects with the
414
+ * failure of whichever transport failed: a client left in a room it was removed from keeps
415
+ * receiving that room's events.
405
416
  */
406
417
  leaveRoom(connectionId: string, roomId: string): Promise<void>;
407
418
  /**
408
419
  * Disconnect a specific connection.
409
420
  *
410
- * Both transports are attempted; the one owning the connection disconnects it.
421
+ * Both transports are asked; the one that holds the connection disconnects it. Rejects when
422
+ * either one could not: the revocation has not reached the connection.
411
423
  */
412
424
  disconnect(connectionId: string, reason?: string): Promise<void>;
425
+ /**
426
+ * Run a per-connection operation on both transports and reject if either failed.
427
+ *
428
+ * One failure is rethrown as it is; both are reported together under
429
+ * `REALTIME_TRANSPORT_UNAVAILABLE`, with every reason in `cause`.
430
+ */
431
+ private settleBoth;
413
432
  /**
414
433
  * Run two transport tasks in parallel via `Promise.allSettled`.
415
434
  *
@@ -81,16 +81,22 @@ declare class WebSocketTransport implements ITransport {
81
81
  private readonly logger;
82
82
  /** Nullable until the gateway's afterInit wires the instance. */
83
83
  private server;
84
+ private warnedUnattached;
84
85
  constructor(connections: ConnectionRegistry, rooms: RoomRegistry, auth: IConnectionAuthenticator, hooks: IConnectionLifecycleHooks, options: BymaxRealtimeModuleOptions);
85
86
  /**
86
87
  * Wire the Socket.IO server. Called by `RealtimeGateway.afterInit`.
87
88
  *
88
- * All emit methods silently no-op until this is called, so the transport is
89
- * safe to construct before the HTTP server is ready.
89
+ * Until this is called an emit delivers nothing and still resolves, with one warning for
90
+ * the first, so the transport is safe to construct before the HTTP server is ready.
90
91
  *
91
92
  * @param server - The live Socket.IO `Server` instance from the NestJS gateway.
92
93
  */
93
94
  setServer(server: Server): void;
95
+ /**
96
+ * The attached server, or `null` before the gateway attaches one. An emit made before
97
+ * then delivers nothing and still resolves; that is logged once, not once per emit.
98
+ */
99
+ private attached;
94
100
  /**
95
101
  * Resolve the map of locally-connected sockets, tolerating both server shapes.
96
102
  *
@@ -193,6 +199,8 @@ declare class WebSocketTransport implements ITransport {
193
199
  *
194
200
  * @param connectionId - The socket `id` of the connection to disconnect.
195
201
  * @param _reason - Optional reason string (unused at the Socket.IO level; passed to `unregisterSocket`).
202
+ * @throws {Error} `REALTIME_TRANSPORT_UNAVAILABLE` when no server is attached or the
203
+ * fan-out throws: the revocation did not leave this node.
196
204
  */
197
205
  disconnect(connectionId: string, _reason?: string): Promise<void>;
198
206
  /**
@@ -344,10 +352,12 @@ declare class RealtimeIoAdapter extends IoAdapter {
344
352
  * parallel via `Promise.allSettled` so a failure in one never aborts the other.
345
353
  * Failures are logged as warnings without rethrowing.
346
354
  *
347
- * `joinRoom`, `leaveRoom`, and `disconnect` attempt both transports tolerantly:
348
- * only the transport that owns the connection will succeed; the other's rejection
349
- * is swallowed. There is no double-delivery because each connection lives on
350
- * exactly one transport.
355
+ * `joinRoom`, `leaveRoom`, and `disconnect` ask both transports and settle both: each
356
+ * transport acts only on a connection it holds, and a connection neither holds is handed
357
+ * to the bus (SSE) and the adapter (WebSocket) for the instance that does. A failure of
358
+ * either one rejects the call, because a revocation or a room change that did not happen
359
+ * must not be reported as done. There is no double-delivery because each connection lives
360
+ * on exactly one transport.
351
361
  *
352
362
  * `kind` reports `'sse'` (the dominant transport); `ITransport.kind` is
353
363
  * `'sse' | 'websocket'` — `'both'` is a module-level `TransportMode`, not a
@@ -393,23 +403,32 @@ declare class CompositeTransport implements ITransport {
393
403
  /**
394
404
  * Join a connection to a room.
395
405
  *
396
- * Both transports are attempted; only the one that owns the connection
397
- * succeeds. The other's failure is expected and swallowed.
406
+ * Both transports are asked; the one that holds the connection acts. Rejects with the
407
+ * failure of whichever transport failed.
398
408
  */
399
409
  joinRoom(connectionId: string, roomId: string): Promise<void>;
400
410
  /**
401
411
  * Remove a connection from a room.
402
412
  *
403
- * Both transports are attempted tolerantly — one will succeed, the other
404
- * may fail silently.
413
+ * Both transports are asked; the one that holds the connection acts. Rejects with the
414
+ * failure of whichever transport failed: a client left in a room it was removed from keeps
415
+ * receiving that room's events.
405
416
  */
406
417
  leaveRoom(connectionId: string, roomId: string): Promise<void>;
407
418
  /**
408
419
  * Disconnect a specific connection.
409
420
  *
410
- * Both transports are attempted; the one owning the connection disconnects it.
421
+ * Both transports are asked; the one that holds the connection disconnects it. Rejects when
422
+ * either one could not: the revocation has not reached the connection.
411
423
  */
412
424
  disconnect(connectionId: string, reason?: string): Promise<void>;
425
+ /**
426
+ * Run a per-connection operation on both transports and reject if either failed.
427
+ *
428
+ * One failure is rethrown as it is; both are reported together under
429
+ * `REALTIME_TRANSPORT_UNAVAILABLE`, with every reason in `cause`.
430
+ */
431
+ private settleBoth;
413
432
  /**
414
433
  * Run two transport tasks in parallel via `Promise.allSettled`.
415
434
  *
@@ -1,6 +1,6 @@
1
1
  import { createRequire } from 'node:module';
2
2
  import { Injectable, Inject, Logger, Global, Module } from '@nestjs/common';
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, describeError, parseCookieHeader, RESERVED_EVENT_NAMES } from '@bymax-one/nest-realtime/internal';
3
+ import { ConnectionRegistry, RoomRegistry, REALTIME_AUTHENTICATOR_TOKEN, REALTIME_HOOKS_TOKEN, REALTIME_OPTIONS_TOKEN, SseTransport, REALTIME_ERROR_CODES, ROOM_PREFIXES, unavailableError, composeForRoot, composeForRootAsync, REALTIME_TRANSPORT_TOKEN, SseSubscriptionHandler, RealtimePubSubSubscriber, createSseController, resolveAuthTenant, assertIdentityIsNotBlank, describeError, parseCookieHeader, RESERVED_EVENT_NAMES } from '@bymax-one/nest-realtime/internal';
4
4
  import { WebSocketServer, WebSocketGateway } from '@nestjs/websockets';
5
5
  import { IoAdapter } from '@nestjs/platform-socket.io';
6
6
 
@@ -42,11 +42,12 @@ var WebSocketTransport = class {
42
42
  logger = new Logger(WebSocketTransport.name);
43
43
  /** Nullable until the gateway's afterInit wires the instance. */
44
44
  server = null;
45
+ warnedUnattached = false;
45
46
  /**
46
47
  * Wire the Socket.IO server. Called by `RealtimeGateway.afterInit`.
47
48
  *
48
- * All emit methods silently no-op until this is called, so the transport is
49
- * safe to construct before the HTTP server is ready.
49
+ * Until this is called an emit delivers nothing and still resolves, with one warning for
50
+ * the first, so the transport is safe to construct before the HTTP server is ready.
50
51
  *
51
52
  * @param server - The live Socket.IO `Server` instance from the NestJS gateway.
52
53
  */
@@ -54,6 +55,19 @@ var WebSocketTransport = class {
54
55
  this.server = server;
55
56
  this.logger.log("Socket.IO server wired to WebSocketTransport");
56
57
  }
58
+ /**
59
+ * The attached server, or `null` before the gateway attaches one. An emit made before
60
+ * then delivers nothing and still resolves; that is logged once, not once per emit.
61
+ */
62
+ attached(op) {
63
+ if (!this.server && !this.warnedUnattached) {
64
+ this.warnedUnattached = true;
65
+ this.logger.warn(
66
+ `${REALTIME_ERROR_CODES.TRANSPORT_UNAVAILABLE} op=${op}: no WebSocket server is attached yet, so emits are dropped until the gateway initialises`
67
+ );
68
+ }
69
+ return this.server;
70
+ }
57
71
  /**
58
72
  * Resolve the map of locally-connected sockets, tolerating both server shapes.
59
73
  *
@@ -168,7 +182,7 @@ var WebSocketTransport = class {
168
182
  * @param data - Payload forwarded to all matching connections.
169
183
  */
170
184
  async emitToUser(userId, event, data) {
171
- this.server?.to(`${ROOM_PREFIXES.USER}:${userId}`).emit(event, data);
185
+ this.attached("emitToUser")?.to(`${ROOM_PREFIXES.USER}:${userId}`).emit(event, data);
172
186
  }
173
187
  /**
174
188
  * Send an event to every connection within a tenant (uses `tenant:{tenantId}` room).
@@ -178,7 +192,7 @@ var WebSocketTransport = class {
178
192
  * @param data - Payload forwarded to all matching connections.
179
193
  */
180
194
  async emitToTenant(tenantId, event, data) {
181
- this.server?.to(`${ROOM_PREFIXES.TENANT}:${tenantId}`).emit(event, data);
195
+ this.attached("emitToTenant")?.to(`${ROOM_PREFIXES.TENANT}:${tenantId}`).emit(event, data);
182
196
  }
183
197
  /**
184
198
  * Send an event to every connection in an arbitrary room.
@@ -188,7 +202,7 @@ var WebSocketTransport = class {
188
202
  * @param data - Payload forwarded to all connections in the room.
189
203
  */
190
204
  async emitToRoom(roomId, event, data) {
191
- this.server?.to(roomId).emit(event, data);
205
+ this.attached("emitToRoom")?.to(roomId).emit(event, data);
192
206
  }
193
207
  /**
194
208
  * Broadcast an event to all connected clients.
@@ -197,7 +211,7 @@ var WebSocketTransport = class {
197
211
  * @param data - Payload forwarded to every connected socket.
198
212
  */
199
213
  async broadcast(event, data) {
200
- this.server?.emit(event, data);
214
+ this.attached("broadcast")?.emit(event, data);
201
215
  }
202
216
  /**
203
217
  * Join a connection to an additional room (updates both Socket.IO and `RoomRegistry`).
@@ -237,13 +251,31 @@ var WebSocketTransport = class {
237
251
  *
238
252
  * @param connectionId - The socket `id` of the connection to disconnect.
239
253
  * @param _reason - Optional reason string (unused at the Socket.IO level; passed to `unregisterSocket`).
254
+ * @throws {Error} `REALTIME_TRANSPORT_UNAVAILABLE` when no server is attached or the
255
+ * fan-out throws: the revocation did not leave this node.
240
256
  */
241
257
  async disconnect(connectionId, _reason) {
242
258
  const server = this.server;
243
- if (!server) return;
244
- const local = this.localSockets()?.get(connectionId);
245
- if (local) local.disconnect(true);
246
- server.in(`${CONNECTION_ROOM_PREFIX}:${connectionId}`).disconnectSockets(true);
259
+ if (!server) {
260
+ throw unavailableError(
261
+ REALTIME_ERROR_CODES.TRANSPORT_UNAVAILABLE,
262
+ WebSocketTransport.name,
263
+ `the WebSocket server is not attached, so ${connectionId} cannot be revoked`,
264
+ new Error("server not attached")
265
+ );
266
+ }
267
+ try {
268
+ const local = this.localSockets()?.get(connectionId);
269
+ if (local) local.disconnect(true);
270
+ server.in(`${CONNECTION_ROOM_PREFIX}:${connectionId}`).disconnectSockets(true);
271
+ } catch (error) {
272
+ throw unavailableError(
273
+ REALTIME_ERROR_CODES.TRANSPORT_UNAVAILABLE,
274
+ WebSocketTransport.name,
275
+ `the revocation of ${connectionId} could not be sent`,
276
+ error
277
+ );
278
+ }
247
279
  }
248
280
  /**
249
281
  * Evict the user's oldest WebSocket connections (FIFO) when over
@@ -339,38 +371,58 @@ var CompositeTransport = class {
339
371
  /**
340
372
  * Join a connection to a room.
341
373
  *
342
- * Both transports are attempted; only the one that owns the connection
343
- * succeeds. The other's failure is expected and swallowed.
374
+ * Both transports are asked; the one that holds the connection acts. Rejects with the
375
+ * failure of whichever transport failed.
344
376
  */
345
377
  async joinRoom(connectionId, roomId) {
346
- await Promise.all([
347
- this.sse.joinRoom(connectionId, roomId).catch(() => void 0),
348
- this.ws.joinRoom(connectionId, roomId).catch(() => void 0)
378
+ await this.settleBoth("joinRoom", connectionId, [
379
+ () => this.sse.joinRoom(connectionId, roomId),
380
+ () => this.ws.joinRoom(connectionId, roomId)
349
381
  ]);
350
382
  }
351
383
  /**
352
384
  * Remove a connection from a room.
353
385
  *
354
- * Both transports are attempted tolerantly — one will succeed, the other
355
- * may fail silently.
386
+ * Both transports are asked; the one that holds the connection acts. Rejects with the
387
+ * failure of whichever transport failed: a client left in a room it was removed from keeps
388
+ * receiving that room's events.
356
389
  */
357
390
  async leaveRoom(connectionId, roomId) {
358
- await Promise.all([
359
- this.sse.leaveRoom(connectionId, roomId).catch(() => void 0),
360
- this.ws.leaveRoom(connectionId, roomId).catch(() => void 0)
391
+ await this.settleBoth("leaveRoom", connectionId, [
392
+ () => this.sse.leaveRoom(connectionId, roomId),
393
+ () => this.ws.leaveRoom(connectionId, roomId)
361
394
  ]);
362
395
  }
363
396
  /**
364
397
  * Disconnect a specific connection.
365
398
  *
366
- * Both transports are attempted; the one owning the connection disconnects it.
399
+ * Both transports are asked; the one that holds the connection disconnects it. Rejects when
400
+ * either one could not: the revocation has not reached the connection.
367
401
  */
368
402
  async disconnect(connectionId, reason) {
369
- await Promise.all([
370
- this.sse.disconnect(connectionId, reason).catch(() => void 0),
371
- this.ws.disconnect(connectionId, reason).catch(() => void 0)
403
+ await this.settleBoth("disconnect", connectionId, [
404
+ () => this.sse.disconnect(connectionId, reason),
405
+ () => this.ws.disconnect(connectionId, reason)
372
406
  ]);
373
407
  }
408
+ /**
409
+ * Run a per-connection operation on both transports and reject if either failed.
410
+ *
411
+ * One failure is rethrown as it is; both are reported together under
412
+ * `REALTIME_TRANSPORT_UNAVAILABLE`, with every reason in `cause`.
413
+ */
414
+ async settleBoth(op, connectionId, tasks) {
415
+ const results = await Promise.allSettled(tasks.map((t) => t()));
416
+ const reasons = results.flatMap((r) => r.status === "rejected" ? [r.reason] : []);
417
+ if (reasons.length === 0) return;
418
+ if (reasons.length === 1) throw reasons[0];
419
+ throw unavailableError(
420
+ REALTIME_ERROR_CODES.TRANSPORT_UNAVAILABLE,
421
+ CompositeTransport.name,
422
+ `${op} of ${connectionId} failed on both transports`,
423
+ new AggregateError(reasons, reasons.map(describeError).join("; "))
424
+ );
425
+ }
374
426
  /**
375
427
  * Run two transport tasks in parallel via `Promise.allSettled`.
376
428
  *
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@bymax-one/nest-realtime",
3
- "version": "1.2.5",
3
+ "version": "1.2.7",
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",
@@ -96,6 +96,7 @@
96
96
  "build": "pnpm clean && tsup",
97
97
  "check:exports": "attw --pack . --profile strict",
98
98
  "check:mutants": "node scripts/check-mutation-directives.mjs",
99
+ "check:api": "node scripts/check-api-surface.mjs",
99
100
  "check:published": "node scripts/check-published-surface.mjs",
100
101
  "check:runtime": "node scripts/check-consumer-runtime.mjs",
101
102
  "benchmark": "node scripts/benchmark/run.mjs",