@bymax-one/nest-realtime 1.2.21 → 1.2.23
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 +28 -1
- package/README.md +26 -26
- package/dist/internal/index.cjs +11 -7
- package/dist/internal/index.d.cts +7 -2
- package/dist/internal/index.d.ts +7 -2
- package/dist/internal/index.mjs +11 -7
- package/package.json +1 -1
package/CHANGELOG.md
CHANGED
|
@@ -7,6 +7,31 @@ Versioning is **not** strict [SemVer](https://semver.org/spec/v2.0.0.html) while
|
|
|
7
7
|
|
|
8
8
|
## [Unreleased]
|
|
9
9
|
|
|
10
|
+
## [1.2.23] - 2026-11-20
|
|
11
|
+
|
|
12
|
+
### Fixed
|
|
13
|
+
|
|
14
|
+
- **A field named `msg` or `level` can no longer reach a log line.** A structured logger reads `msg` as the text of a line and `level` as its severity, so a field of either name could change what a library line says or how it is filed. `logEvent` drops them, as it already did `err`; `event` and `message` stay the library's own.
|
|
15
|
+
|
|
16
|
+
### Documentation
|
|
17
|
+
|
|
18
|
+
- **The README and the `tenantResolver` documentation say that the resolver receives a plain copy.** The options table, the paragraph on identity and the JSDoc state that the copy has its own enumerable properties only and no `tenantId` when the tenant is absent or `null`.
|
|
19
|
+
|
|
20
|
+
## [1.2.22] - 2026-11-20
|
|
21
|
+
|
|
22
|
+
### Fixed
|
|
23
|
+
|
|
24
|
+
- **The tenant of an authentication result is read once.** The routing tenant was read from the result more than once, so a getter that answers differently the second time could route on a value that was not the one tested. It is read once, the rest of the result is copied beside it, and a `tenantResolver` is given that copy, so a resolver that reads `auth.tenantId` reads the same value.
|
|
25
|
+
- **A field named `err` can no longer stand for the error of a log line.** `logEvent` wrote a caller's `err` field when no error was passed, and `err` is where a logger's serializer reads an error from. Only the error argument writes `err` now. The `logEvent` documentation also says that a field whose read throws, such as a getter, loses the line instead of throwing.
|
|
26
|
+
|
|
27
|
+
#### Apply to a derived backend
|
|
28
|
+
|
|
29
|
+
A `tenantResolver` now receives a plain copy of the authentication result, with its own enumerable properties only, and not the authenticator's original object. A resolver that relies on a prototype method of that object, on its identity, or on a property that is not enumerable must read what it needs in the authenticator and carry it in the result's `metadata`. The result the library hands to the rest of the code was already such a copy.
|
|
30
|
+
|
|
31
|
+
### Documentation
|
|
32
|
+
|
|
33
|
+
- **The README says what a getter that throws on the authenticator's result does.** The error is the host's own and is not wrapped: the handshake fails, it is logged under `err` and counted as `reason="error"`.
|
|
34
|
+
|
|
10
35
|
## [1.2.21] - 2026-11-20
|
|
11
36
|
|
|
12
37
|
### Fixed
|
|
@@ -1237,7 +1262,9 @@ First published release.
|
|
|
1237
1262
|
rather than by the manual sweep that raised the NestJS floors — that sweep
|
|
1238
1263
|
asked about NestJS and never put the same question to the other ten peers.
|
|
1239
1264
|
|
|
1240
|
-
[Unreleased]: https://github.com/bymaxone/nest-realtime/compare/v1.2.
|
|
1265
|
+
[Unreleased]: https://github.com/bymaxone/nest-realtime/compare/v1.2.23...HEAD
|
|
1266
|
+
[1.2.23]: https://github.com/bymaxone/nest-realtime/compare/v1.2.22...v1.2.23
|
|
1267
|
+
[1.2.22]: https://github.com/bymaxone/nest-realtime/compare/v1.2.21...v1.2.22
|
|
1241
1268
|
[1.2.21]: https://github.com/bymaxone/nest-realtime/compare/v1.2.20...v1.2.21
|
|
1242
1269
|
[1.2.20]: https://github.com/bymaxone/nest-realtime/compare/v1.2.19...v1.2.20
|
|
1243
1270
|
[1.2.19]: https://github.com/bymaxone/nest-realtime/compare/v1.2.18...v1.2.19
|
package/README.md
CHANGED
|
@@ -141,7 +141,7 @@ pnpm add socket.io-client
|
|
|
141
141
|
|
|
142
142
|
### 2. Implement the Authenticator Interface
|
|
143
143
|
|
|
144
|
-
This is the only interface you are required to provide. The library calls it once per connection and never inspects the credential itself.
|
|
144
|
+
This is the only interface you are required to provide. The library calls it once per connection and never inspects the credential itself. What it returns is your code's own object: a getter on it that throws raises that error as it is, the handshake fails, the error is logged under `err` and counted as `reason="error"`, and the client is sent nothing of it.
|
|
145
145
|
|
|
146
146
|
```typescript
|
|
147
147
|
import type {
|
|
@@ -342,23 +342,23 @@ With `redisAdapter`, the adapter registers `@socket.io/redis-adapter` and calls
|
|
|
342
342
|
|
|
343
343
|
All options are passed to `forRoot()` / `forRootAsync()`. Only `transport` and `authenticator` are required.
|
|
344
344
|
|
|
345
|
-
| Group | Key Options
|
|
346
|
-
| -------------------------- |
|
|
347
|
-
| **transport** | `'sse'` \| `'websocket'` \| `'both'`
|
|
348
|
-
| **authenticator** | `IConnectionAuthenticator`
|
|
349
|
-
| **tenantResolver** | `(auth) => string \| undefined \| null` — derives `tenantId` from the auth result, on **both** transports; `undefined` and `null` mean "no opinion" and fall back
|
|
350
|
-
| **hooks** | `onConnect`, `onDisconnect`, `onError`, `onReauthenticationFailed`, `onDeliveryFailure` (fire-and-forget)
|
|
351
|
-
| **hookTimeoutMs** | How long the library waits for a hook it awaits (`onDisconnect` on both transports, WebSocket `onConnect`) before giving up on it; integer from 1 to 2147483647
|
|
352
|
-
| **onConnectFailure** | What a failing `onConnect` does to its connection: `'ignore'` logs it and keeps the connection, `'close'` logs it and closes the connection on both transports, after the hook has run; anything else is refused at start-up
|
|
353
|
-
| **authenticateTimeoutMs** | How long a handshake waits for `authenticate` before it is refused (SSE `503`, WebSocket the generic error); integer from 1 to 2147483647
|
|
354
|
-
| **maxPendingHandshakes** | How many calls to `authenticate` may be waiting at once, across both transports; over it a handshake is refused at once without calling it; integer >= 1
|
|
355
|
-
| **maxConnections** | How many connections one instance holds, both transports together; a handshake past it is refused before `authenticate` is called (SSE `503`, WebSocket the generic error); integer >= 1, no way to switch it off
|
|
356
|
-
| **pubsub** | `IRealtimePubSub` — cross-instance fan-out for SSE
|
|
357
|
-
| **offlineQueue** | `IOfflineQueueStorage` — events held while a user is away
|
|
358
|
-
| **presence** | `IPresenceStorage` — contract for your own presence tracking; the library never calls it
|
|
359
|
-
| **sse** | `endpoint`, `heartbeatMs`, `replayBufferSize`, `replayTtlMs`, `replayMaxIdleUsers`, `maxConnectionsPerUser`, `emitConnectionEvent`, `maxQueuedBytes`, `maxQueuedEvents`, `stallHeartbeats`
|
|
360
|
-
| **websocket** | `namespace`, `cors`, `maxHttpBufferSize`, `pingIntervalMs`, `pingTimeoutMs`, `maxConnectionsPerUser`, `emitConnectionEvent`, `redisAdapter`
|
|
361
|
-
| **reauthenticationPolicy** | `intervalSeconds`, `onFailure` (`'disconnect'` \| `'event'`), `cacheTtlMs`, `revalidateTimeoutMs`, `concurrency`
|
|
345
|
+
| Group | Key Options | Default |
|
|
346
|
+
| -------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------- |
|
|
347
|
+
| **transport** | `'sse'` \| `'websocket'` \| `'both'` | — (**required**) |
|
|
348
|
+
| **authenticator** | `IConnectionAuthenticator` | — (**required**) |
|
|
349
|
+
| **tenantResolver** | `(auth) => string \| undefined \| null` — derives `tenantId` from the auth result (it receives a plain copy of that result, which has no `tenantId` when the tenant is absent or `null`), on **both** transports; `undefined` and `null` mean "no opinion" and fall back | `auth.tenantId` |
|
|
350
|
+
| **hooks** | `onConnect`, `onDisconnect`, `onError`, `onReauthenticationFailed`, `onDeliveryFailure` (fire-and-forget) | — |
|
|
351
|
+
| **hookTimeoutMs** | How long the library waits for a hook it awaits (`onDisconnect` on both transports, WebSocket `onConnect`) before giving up on it; integer from 1 to 2147483647 | `5000` |
|
|
352
|
+
| **onConnectFailure** | What a failing `onConnect` does to its connection: `'ignore'` logs it and keeps the connection, `'close'` logs it and closes the connection on both transports, after the hook has run; anything else is refused at start-up | `'ignore'` |
|
|
353
|
+
| **authenticateTimeoutMs** | How long a handshake waits for `authenticate` before it is refused (SSE `503`, WebSocket the generic error); integer from 1 to 2147483647 | `10000` |
|
|
354
|
+
| **maxPendingHandshakes** | How many calls to `authenticate` may be waiting at once, across both transports; over it a handshake is refused at once without calling it; integer >= 1 | `1000` |
|
|
355
|
+
| **maxConnections** | How many connections one instance holds, both transports together; a handshake past it is refused before `authenticate` is called (SSE `503`, WebSocket the generic error); integer >= 1, no way to switch it off | `10000` |
|
|
356
|
+
| **pubsub** | `IRealtimePubSub` — cross-instance fan-out for SSE | `InMemoryPubSub` |
|
|
357
|
+
| **offlineQueue** | `IOfflineQueueStorage` — events held while a user is away | — (disabled) |
|
|
358
|
+
| **presence** | `IPresenceStorage` — contract for your own presence tracking; the library never calls it | — (disabled) |
|
|
359
|
+
| **sse** | `endpoint`, `heartbeatMs`, `replayBufferSize`, `replayTtlMs`, `replayMaxIdleUsers`, `maxConnectionsPerUser`, `emitConnectionEvent`, `maxQueuedBytes`, `maxQueuedEvents`, `stallHeartbeats` | `/realtime/sse`, `30000`, `100`, `300000`, `1000`, `5`, `true`, `2097152`, `1000`, `3` |
|
|
360
|
+
| **websocket** | `namespace`, `cors`, `maxHttpBufferSize`, `pingIntervalMs`, `pingTimeoutMs`, `maxConnectionsPerUser`, `emitConnectionEvent`, `redisAdapter` | `'/'`, — (Socket.IO defaults), `5` for `maxConnectionsPerUser` |
|
|
361
|
+
| **reauthenticationPolicy** | `intervalSeconds`, `onFailure` (`'disconnect'` \| `'event'`), `cacheTtlMs`, `revalidateTimeoutMs`, `concurrency` | `300`, `'disconnect'`, `60000`, `10000`, `8` |
|
|
362
362
|
|
|
363
363
|
`sse.heartbeatMs` must be between 5,000 and 90,000 ms. Any other value, including `NaN` and a non-number, stops the application at start-up with `REALTIME_INVALID_OPTIONS`. `websocket.pingIntervalMs` and `websocket.pingTimeoutMs` must be integers from 1 to 2147483647 (Socket.IO runs both as timers, and Node runs a longer one as 1 ms). `sse.replayTtlMs` must be an integer from 1 to 2147483647 and `sse.replayMaxIdleUsers` an integer of 1 or more. `sse.maxQueuedBytes`, `sse.maxQueuedEvents` and `sse.stallHeartbeats` must be integers of 0 or more, and `0` switches that bound off.
|
|
364
364
|
|
|
@@ -497,13 +497,13 @@ import {
|
|
|
497
497
|
export class ObservabilityModule {}
|
|
498
498
|
```
|
|
499
499
|
|
|
500
|
-
| Metric | Type | Labels | Meaning
|
|
501
|
-
| ------------------------------------------ | ------- | ---------------------------------------------------------- |
|
|
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); a connection that `onConnectFailure: 'close'` closes was admitted first, and is not counted.
|
|
504
|
-
| `bymax_realtime_evictions_total` | counter | `reason` = `per_user_cap`, `slow_consumer`, `revoked` | Connections closed by the library or by a revocation.
|
|
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
|
-
| `bymax_realtime_slow_consumer_drops_total` | counter | none | Connections cut for not reading what they were sent.
|
|
500
|
+
| Metric | Type | Labels | Meaning |
|
|
501
|
+
| ------------------------------------------ | ------- | ---------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
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); a connection that `onConnectFailure: 'close'` closes was admitted first, and is not counted. |
|
|
504
|
+
| `bymax_realtime_evictions_total` | counter | `reason` = `per_user_cap`, `slow_consumer`, `revoked` | Connections closed by the library or by a revocation. |
|
|
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
|
+
| `bymax_realtime_slow_consumer_drops_total` | counter | none | Connections cut for not reading what they were sent. |
|
|
507
507
|
|
|
508
508
|
A label is one of the values listed and never an id, a tenant or a user. A revocation is counted on the instance that was asked to make it, once it has closed the connection or handed the request to the bus.
|
|
509
509
|
|
|
@@ -777,7 +777,7 @@ Reference implementations shipped: `InMemoryPubSub` (default), `RedisRealtimePub
|
|
|
777
777
|
|
|
778
778
|
To place a connection in no tenant, **omit `tenantId`**. The runtime also accepts `undefined` or `null`, but whether those type-check depends on the consumer's `tsconfig` (`exactOptionalPropertyTypes` rejects `undefined`, `strictNullChecks` rejects `null`), so omission is the only form that compiles everywhere.
|
|
779
779
|
|
|
780
|
-
`tenantResolver` cannot clear a tenant. Resolution is `tenantResolver?.(auth) ?? auth.tenantId`, so a resolver returning `undefined` or `null` means "no opinion" and the authenticator's tenant stays. Decide the absent case in the authenticator.
|
|
780
|
+
`tenantResolver` cannot clear a tenant. It receives a plain copy of the authentication result, with its own enumerable properties only and no `tenantId` when the tenant is absent or `null`, not the authenticator's original object. Resolution is `tenantResolver?.(auth) ?? auth.tenantId`, so a resolver returning `undefined` or `null` means "no opinion" and the authenticator's tenant stays. Decide the absent case in the authenticator.
|
|
781
781
|
|
|
782
782
|
#### Carrying handshake context into the hooks
|
|
783
783
|
|
package/dist/internal/index.cjs
CHANGED
|
@@ -567,9 +567,13 @@ var REALTIME_LOG_EVENTS = [
|
|
|
567
567
|
"REALTIME_COMPOSITE_PARTIAL_FAILURE",
|
|
568
568
|
"REALTIME_SERVER_NOT_ATTACHED"
|
|
569
569
|
];
|
|
570
|
+
var RESERVED_KEYS = ["err", "msg", "level"];
|
|
570
571
|
function logEvent(logger, level, event, message, fields = {}, error) {
|
|
571
572
|
try {
|
|
572
|
-
|
|
573
|
+
const line = { ...fields, event, message };
|
|
574
|
+
for (const key of RESERVED_KEYS) delete line[key];
|
|
575
|
+
if (error !== void 0) line["err"] = error;
|
|
576
|
+
logger[level](line);
|
|
573
577
|
} catch {
|
|
574
578
|
}
|
|
575
579
|
}
|
|
@@ -857,12 +861,12 @@ function isBlank(value) {
|
|
|
857
861
|
return typeof value !== "string" || value.trim().length === 0;
|
|
858
862
|
}
|
|
859
863
|
function resolveAuthTenant(options, auth) {
|
|
860
|
-
const
|
|
861
|
-
|
|
862
|
-
|
|
863
|
-
|
|
864
|
-
|
|
865
|
-
return { ...
|
|
864
|
+
const { tenantId: own, ...rest } = auth;
|
|
865
|
+
const resolved = options.tenantResolver?.(
|
|
866
|
+
own === void 0 || own === null ? rest : { ...rest, tenantId: own }
|
|
867
|
+
) ?? own;
|
|
868
|
+
if (resolved === void 0 || resolved === null) return rest;
|
|
869
|
+
return { ...rest, tenantId: resolved };
|
|
866
870
|
}
|
|
867
871
|
function assertIdentityIsNotBlank(auth) {
|
|
868
872
|
if (isBlank(auth.userId)) {
|
|
@@ -479,7 +479,10 @@ interface BymaxRealtimeModuleOptions {
|
|
|
479
479
|
/**
|
|
480
480
|
* Derive the tenant a connection routes on from the authenticated result.
|
|
481
481
|
*
|
|
482
|
-
* Applied on **both** transports.
|
|
482
|
+
* Applied on **both** transports. It receives a plain copy of the authentication
|
|
483
|
+
* result, with its own enumerable properties only and no `tenantId` when the tenant
|
|
484
|
+
* is absent or `null`, not the authenticator's original object. `undefined` and
|
|
485
|
+
* `null` both mean "no opinion"
|
|
483
486
|
* and fall back to `auth.tenantId` rather than clearing it; to place a connection
|
|
484
487
|
* in no tenant, return a result without one from the authenticator. `null` is in
|
|
485
488
|
* the signature because the implementation accepts it and a type narrower than the
|
|
@@ -2305,7 +2308,9 @@ type LogFields = Readonly<Record<string, string | number | boolean>>;
|
|
|
2305
2308
|
* @param level - `warn` for what degrades service, `error` for what fails an operation.
|
|
2306
2309
|
* @param event - The stable code of the condition.
|
|
2307
2310
|
* @param message - Human text; the library's own wording, with no host-supplied value in it.
|
|
2308
|
-
* @param fields - Closed or numeric fields.
|
|
2311
|
+
* @param fields - Closed or numeric fields, built by the library. A key named `event` or `message` is replaced by the
|
|
2312
|
+
* library's own value, and one named `err`, `msg` or `level` is dropped, and a field whose read throws, such as a getter, loses the line like any other
|
|
2313
|
+
* throw while writing.
|
|
2309
2314
|
* @param error - What was thrown, when the event reports a failure. It goes under `err` as the value itself, never
|
|
2310
2315
|
* as text in `message`, so the logger's serializer and redaction apply to it: an error raised by host code can
|
|
2311
2316
|
* carry a user or a tenant, and the library's own line must not.
|
package/dist/internal/index.d.ts
CHANGED
|
@@ -479,7 +479,10 @@ interface BymaxRealtimeModuleOptions {
|
|
|
479
479
|
/**
|
|
480
480
|
* Derive the tenant a connection routes on from the authenticated result.
|
|
481
481
|
*
|
|
482
|
-
* Applied on **both** transports.
|
|
482
|
+
* Applied on **both** transports. It receives a plain copy of the authentication
|
|
483
|
+
* result, with its own enumerable properties only and no `tenantId` when the tenant
|
|
484
|
+
* is absent or `null`, not the authenticator's original object. `undefined` and
|
|
485
|
+
* `null` both mean "no opinion"
|
|
483
486
|
* and fall back to `auth.tenantId` rather than clearing it; to place a connection
|
|
484
487
|
* in no tenant, return a result without one from the authenticator. `null` is in
|
|
485
488
|
* the signature because the implementation accepts it and a type narrower than the
|
|
@@ -2305,7 +2308,9 @@ type LogFields = Readonly<Record<string, string | number | boolean>>;
|
|
|
2305
2308
|
* @param level - `warn` for what degrades service, `error` for what fails an operation.
|
|
2306
2309
|
* @param event - The stable code of the condition.
|
|
2307
2310
|
* @param message - Human text; the library's own wording, with no host-supplied value in it.
|
|
2308
|
-
* @param fields - Closed or numeric fields.
|
|
2311
|
+
* @param fields - Closed or numeric fields, built by the library. A key named `event` or `message` is replaced by the
|
|
2312
|
+
* library's own value, and one named `err`, `msg` or `level` is dropped, and a field whose read throws, such as a getter, loses the line like any other
|
|
2313
|
+
* throw while writing.
|
|
2309
2314
|
* @param error - What was thrown, when the event reports a failure. It goes under `err` as the value itself, never
|
|
2310
2315
|
* as text in `message`, so the logger's serializer and redaction apply to it: an error raised by host code can
|
|
2311
2316
|
* carry a user or a tenant, and the library's own line must not.
|
package/dist/internal/index.mjs
CHANGED
|
@@ -565,9 +565,13 @@ var REALTIME_LOG_EVENTS = [
|
|
|
565
565
|
"REALTIME_COMPOSITE_PARTIAL_FAILURE",
|
|
566
566
|
"REALTIME_SERVER_NOT_ATTACHED"
|
|
567
567
|
];
|
|
568
|
+
var RESERVED_KEYS = ["err", "msg", "level"];
|
|
568
569
|
function logEvent(logger, level, event, message, fields = {}, error) {
|
|
569
570
|
try {
|
|
570
|
-
|
|
571
|
+
const line = { ...fields, event, message };
|
|
572
|
+
for (const key of RESERVED_KEYS) delete line[key];
|
|
573
|
+
if (error !== void 0) line["err"] = error;
|
|
574
|
+
logger[level](line);
|
|
571
575
|
} catch {
|
|
572
576
|
}
|
|
573
577
|
}
|
|
@@ -855,12 +859,12 @@ function isBlank(value) {
|
|
|
855
859
|
return typeof value !== "string" || value.trim().length === 0;
|
|
856
860
|
}
|
|
857
861
|
function resolveAuthTenant(options, auth) {
|
|
858
|
-
const
|
|
859
|
-
|
|
860
|
-
|
|
861
|
-
|
|
862
|
-
|
|
863
|
-
return { ...
|
|
862
|
+
const { tenantId: own, ...rest } = auth;
|
|
863
|
+
const resolved = options.tenantResolver?.(
|
|
864
|
+
own === void 0 || own === null ? rest : { ...rest, tenantId: own }
|
|
865
|
+
) ?? own;
|
|
866
|
+
if (resolved === void 0 || resolved === null) return rest;
|
|
867
|
+
return { ...rest, tenantId: resolved };
|
|
864
868
|
}
|
|
865
869
|
function assertIdentityIsNotBlank(auth) {
|
|
866
870
|
if (isBlank(auth.userId)) {
|
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.23",
|
|
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",
|