@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 +18 -1
- package/README.md +5 -2
- package/dist/internal/index.cjs +60 -15
- package/dist/internal/index.d.cts +2 -1
- package/dist/internal/index.d.ts +2 -1
- package/dist/internal/index.mjs +60 -15
- package/dist/websocket/index.cjs +13 -3
- package/dist/websocket/index.mjs +13 -3
- package/package.json +1 -1
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.
|
|
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 |
|
package/dist/internal/index.cjs
CHANGED
|
@@ -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,
|
|
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
|
-
|
|
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
|
|
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
|
|
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
|
package/dist/internal/index.d.ts
CHANGED
|
@@ -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
|
package/dist/internal/index.mjs
CHANGED
|
@@ -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,
|
|
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
|
-
|
|
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
|
|
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
|
|
3116
|
+
`Subscribed to the realtime channel; remote events and revocations reach this instance`
|
|
3072
3117
|
);
|
|
3073
3118
|
}
|
|
3074
3119
|
markDown(wording, error) {
|
package/dist/websocket/index.cjs
CHANGED
|
@@ -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
|
|
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",
|
package/dist/websocket/index.mjs
CHANGED
|
@@ -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
|
|
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.
|
|
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",
|