@bymax-one/nest-realtime 1.1.0 → 1.1.1
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 +53 -1
- package/README.md +44 -0
- package/dist/internal/index.cjs +3 -0
- package/dist/internal/index.d.cts +29 -3
- package/dist/internal/index.d.ts +29 -3
- package/dist/internal/index.mjs +3 -0
- package/dist/websocket/index.cjs +2 -0
- package/dist/websocket/index.mjs +2 -0
- package/package.json +2 -2
package/CHANGELOG.md
CHANGED
|
@@ -5,6 +5,57 @@ All notable changes to this project will be documented in this file.
|
|
|
5
5
|
The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
|
|
6
6
|
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
|
|
7
7
|
|
|
8
|
+
## [1.1.1] - 2026-08-21
|
|
9
|
+
|
|
10
|
+
### Added
|
|
11
|
+
|
|
12
|
+
- **`ConnectionEventMeta` now carries `roles`.** `IConnectionAuthenticator.authenticate` returns
|
|
13
|
+
`roles` and `ConnectionRecord.originalAuth` stores them, but the meta the lifecycle hooks
|
|
14
|
+
receive dropped them — so a host authenticating by role could not act on the role at
|
|
15
|
+
`onConnect`, the one point that has a `connectionId` and knows the connection is new. With no
|
|
16
|
+
role-scoped fan-out and a registry indexed by id, userId and tenantId, a room is the only
|
|
17
|
+
mechanism for "these connections and not those", and a room could not be built on a value that
|
|
18
|
+
never arrived. Threaded through all five meta construction sites — SSE and WebSocket
|
|
19
|
+
`onConnect`/`onDisconnect` plus `onReauthenticationFailed` — because roles present at connect
|
|
20
|
+
and absent at disconnect would be a field that lies by omission exactly when a host cleans up.
|
|
21
|
+
|
|
22
|
+
**This adds a required key.** Reading the meta is unaffected, which is what a hook does; code
|
|
23
|
+
that *constructs* a `ConnectionEventMeta` (typically a test fixture) must now supply `roles`.
|
|
24
|
+
`undefined` stays meaningful for an authenticator that returns none.
|
|
25
|
+
|
|
26
|
+
Roles are carried, never interpreted: there is deliberately no `emitToRole`. Indexing a
|
|
27
|
+
fan-out on a role would put the consumer's authorization vocabulary into the transport's API,
|
|
28
|
+
and `meta.roles` is a connect-time snapshot — a role-indexed emit would look authoritative
|
|
29
|
+
while reading state that can go stale. Room-plus-`onConnect` leaves that decision with the
|
|
30
|
+
host. The pattern is documented in the README and covered by an executable test.
|
|
31
|
+
|
|
32
|
+
### Fixed
|
|
33
|
+
|
|
34
|
+
- **`forRootAsync` rejected typed factories and abstract `inject` tokens.** `useFactory` was an
|
|
35
|
+
arrow-property signature, so `strictFunctionTypes` checked it contravariantly and rejected
|
|
36
|
+
every factory whose parameters carried real provider types — including the
|
|
37
|
+
`useFactory: (cfg: ConfigService) => ...` example in this module's own JSDoc, which had never
|
|
38
|
+
typechecked for a consumer. Method shorthand is bivariant, which is what makes `inject` usable.
|
|
39
|
+
Separately, `inject` accepted only `Type<unknown>`, a non-abstract constructor type, which
|
|
40
|
+
excluded Nest's own abstract tokens — `ModuleRef` among them, and therefore the documented
|
|
41
|
+
role-scoped room pattern. Widened with `Abstract<unknown>`.
|
|
42
|
+
|
|
43
|
+
### Documentation
|
|
44
|
+
|
|
45
|
+
- The README's Rooms section gains a **role-scoped delivery** subsection: how to build a
|
|
46
|
+
role room in `onConnect`, why there is no `emitToRole`, and the snapshot semantics of
|
|
47
|
+
`meta.roles` — a `revalidate` that keeps a connection alive does not refresh it.
|
|
48
|
+
- The `[Unreleased]` compare link pointed at `v1.0.5`, left behind when 1.1.0 shipped, so it
|
|
49
|
+
showed the whole 1.1.0 release as unreleased.
|
|
50
|
+
|
|
51
|
+
### Tests
|
|
52
|
+
|
|
53
|
+
- The documented role-scoped room pattern is now an executable test rather than prose
|
|
54
|
+
(`realtime.module.documented-patterns.spec.ts`): it boots the module exactly as the README
|
|
55
|
+
shows and asserts both halves — the admin connection reaches `role:admin`, and a `viewer` and
|
|
56
|
+
a roles-`undefined` connection reach nothing. `pnpm typecheck` covers it, so reverting either
|
|
57
|
+
option-type change fails there.
|
|
58
|
+
|
|
8
59
|
## [1.1.0] - 2026-08-11
|
|
9
60
|
|
|
10
61
|
### Changed
|
|
@@ -242,7 +293,8 @@ First published release.
|
|
|
242
293
|
rather than by the manual sweep that raised the NestJS floors — that sweep
|
|
243
294
|
asked about NestJS and never put the same question to the other ten peers.
|
|
244
295
|
|
|
245
|
-
[Unreleased]: https://github.com/bymaxone/nest-realtime/compare/v1.
|
|
296
|
+
[Unreleased]: https://github.com/bymaxone/nest-realtime/compare/v1.1.1...HEAD
|
|
297
|
+
[1.1.1]: https://github.com/bymaxone/nest-realtime/compare/v1.1.0...v1.1.1
|
|
246
298
|
[1.1.0]: https://github.com/bymaxone/nest-realtime/compare/v1.0.6...v1.1.0
|
|
247
299
|
[1.0.6]: https://github.com/bymaxone/nest-realtime/compare/v1.0.5...v1.0.6
|
|
248
300
|
[1.0.5]: https://github.com/bymaxone/nest-realtime/compare/v1.0.4...v1.0.5
|
package/README.md
CHANGED
|
@@ -544,6 +544,50 @@ composeRoomId('TENANT', tenantId) // → "tenant:t_acme"
|
|
|
544
544
|
composeRoomId('RESOURCE', 'invoice', invoiceId) // → "resource:invoice:42"
|
|
545
545
|
```
|
|
546
546
|
|
|
547
|
+
#### Role-scoped delivery
|
|
548
|
+
|
|
549
|
+
There is no `emitToRole`. Roles are the consumer's authorization vocabulary, not
|
|
550
|
+
the transport's — the library carries them through without interpreting them (see
|
|
551
|
+
[Auth Inversion](#auth-inversion)). To deliver to a subset of connections by role,
|
|
552
|
+
build a room for it in `onConnect`, where `ConnectionEventMeta.roles` carries the
|
|
553
|
+
snapshot the authenticator produced:
|
|
554
|
+
|
|
555
|
+
```typescript
|
|
556
|
+
import { ModuleRef } from '@nestjs/core'
|
|
557
|
+
import { BymaxRealtimeModule, RealtimeService } from '@bymax-one/nest-realtime'
|
|
558
|
+
|
|
559
|
+
BymaxRealtimeModule.forRootAsync({
|
|
560
|
+
transport: 'sse',
|
|
561
|
+
inject: [ModuleRef],
|
|
562
|
+
useFactory: (moduleRef: ModuleRef) => ({
|
|
563
|
+
transport: 'sse' as const,
|
|
564
|
+
authenticator: new CookieAuthenticator(),
|
|
565
|
+
hooks: {
|
|
566
|
+
onConnect: async (meta) => {
|
|
567
|
+
if (!meta.roles?.includes('admin')) return
|
|
568
|
+
// Resolved lazily: the hook runs per connection, long after bootstrap, so
|
|
569
|
+
// `RealtimeService` — provided by this very module — cannot be injected
|
|
570
|
+
// into the factory that configures it.
|
|
571
|
+
const realtime = moduleRef.get(RealtimeService)
|
|
572
|
+
await realtime.joinRoom(meta.connectionId, 'role:admin')
|
|
573
|
+
},
|
|
574
|
+
},
|
|
575
|
+
}),
|
|
576
|
+
})
|
|
577
|
+
```
|
|
578
|
+
|
|
579
|
+
Then deliver to exactly those connections from any provider that injects
|
|
580
|
+
`RealtimeService`:
|
|
581
|
+
|
|
582
|
+
```typescript
|
|
583
|
+
await this.realtime.emitToRoom('role:admin', 'audit.log', entry)
|
|
584
|
+
```
|
|
585
|
+
|
|
586
|
+
`meta.roles` is a snapshot taken at connect time; a later `revalidate` that keeps
|
|
587
|
+
the connection alive does not refresh it. When a role can be revoked mid-session,
|
|
588
|
+
make `revalidate` return `false` so the connection is torn down and re-established
|
|
589
|
+
with the new roles.
|
|
590
|
+
|
|
547
591
|
### Reserved Events
|
|
548
592
|
|
|
549
593
|
Emitted by the library. Do not reuse these names for application events.
|
package/dist/internal/index.cjs
CHANGED
|
@@ -525,6 +525,7 @@ exports.SseTransport = class SseTransport {
|
|
|
525
525
|
connectionId: record.connectionId,
|
|
526
526
|
userId: record.userId,
|
|
527
527
|
tenantId: record.tenantId,
|
|
528
|
+
roles: record.originalAuth.roles,
|
|
528
529
|
transport: "sse",
|
|
529
530
|
ip: record.ip,
|
|
530
531
|
userAgent: record.userAgent,
|
|
@@ -761,6 +762,7 @@ function buildMeta(record) {
|
|
|
761
762
|
connectionId: record.connectionId,
|
|
762
763
|
userId: record.userId,
|
|
763
764
|
tenantId: record.tenantId,
|
|
765
|
+
roles: record.originalAuth.roles,
|
|
764
766
|
transport: "sse",
|
|
765
767
|
ip: record.ip,
|
|
766
768
|
userAgent: record.userAgent,
|
|
@@ -1135,6 +1137,7 @@ exports.ReauthenticationService = class ReauthenticationService {
|
|
|
1135
1137
|
connectionId: conn.connectionId,
|
|
1136
1138
|
userId: conn.userId,
|
|
1137
1139
|
tenantId: conn.tenantId,
|
|
1140
|
+
roles: conn.originalAuth.roles,
|
|
1138
1141
|
transport: "sse",
|
|
1139
1142
|
ip: conn.ip,
|
|
1140
1143
|
userAgent: conn.userAgent,
|
|
@@ -1,4 +1,4 @@
|
|
|
1
|
-
import { ModuleMetadata, Type, Provider, Logger, DynamicModule, MessageEvent, OnModuleInit, OnApplicationShutdown } from '@nestjs/common';
|
|
1
|
+
import { ModuleMetadata, Type, Abstract, Provider, Logger, DynamicModule, MessageEvent, OnModuleInit, OnApplicationShutdown } from '@nestjs/common';
|
|
2
2
|
import { Subject, Observable } from 'rxjs';
|
|
3
3
|
import { Redis } from 'ioredis';
|
|
4
4
|
|
|
@@ -121,6 +121,16 @@ interface ConnectionEventMeta {
|
|
|
121
121
|
readonly connectionId: string;
|
|
122
122
|
readonly userId: string;
|
|
123
123
|
readonly tenantId: string | undefined;
|
|
124
|
+
/**
|
|
125
|
+
* Roles the authenticator returned for this connection, as a snapshot taken at
|
|
126
|
+
* connect time — `undefined` when the authenticator returned none.
|
|
127
|
+
*
|
|
128
|
+
* The library never interprets a role; it carries the consumer's own
|
|
129
|
+
* authorization vocabulary through so `onConnect` can act on it (typically by
|
|
130
|
+
* joining the connection to a role-scoped room). A later `revalidate` that
|
|
131
|
+
* keeps the connection alive does not refresh this snapshot.
|
|
132
|
+
*/
|
|
133
|
+
readonly roles: readonly string[] | undefined;
|
|
124
134
|
readonly transport: 'sse' | 'websocket';
|
|
125
135
|
readonly ip: string;
|
|
126
136
|
readonly userAgent: string | undefined;
|
|
@@ -324,8 +334,24 @@ interface BymaxRealtimeModuleAsyncOptions extends Pick<ModuleMetadata, 'imports'
|
|
|
324
334
|
* `transport` the factory resolves; a mismatch fails fast at bootstrap.
|
|
325
335
|
*/
|
|
326
336
|
transport: TransportMode;
|
|
327
|
-
|
|
328
|
-
|
|
337
|
+
/**
|
|
338
|
+
* Factory producing the options, receiving whatever `inject` resolves.
|
|
339
|
+
*
|
|
340
|
+
* Declared in method shorthand on purpose: that signature is bivariant, so a
|
|
341
|
+
* consumer can annotate the parameters with the real provider types
|
|
342
|
+
* (`(cfg: ConfigService) => ...`) instead of `unknown`. An arrow-property
|
|
343
|
+
* signature would be checked contravariantly under `strictFunctionTypes` and
|
|
344
|
+
* reject every typed factory, which is the whole point of `inject`.
|
|
345
|
+
*/
|
|
346
|
+
useFactory?(...args: unknown[]): BymaxRealtimeModuleOptions | Promise<BymaxRealtimeModuleOptions>;
|
|
347
|
+
/**
|
|
348
|
+
* Providers to resolve and pass to `useFactory`, positionally.
|
|
349
|
+
*
|
|
350
|
+
* `Abstract<unknown>` is included because Nest's own injectable tokens are
|
|
351
|
+
* abstract classes — `ModuleRef` among them — and `Type<unknown>` alone is a
|
|
352
|
+
* non-abstract constructor type that excludes them.
|
|
353
|
+
*/
|
|
354
|
+
inject?: readonly (string | symbol | Type<unknown> | Abstract<unknown>)[];
|
|
329
355
|
useExisting?: Type<BymaxRealtimeModuleOptionsFactory>;
|
|
330
356
|
useClass?: Type<BymaxRealtimeModuleOptionsFactory>;
|
|
331
357
|
/**
|
package/dist/internal/index.d.ts
CHANGED
|
@@ -1,4 +1,4 @@
|
|
|
1
|
-
import { ModuleMetadata, Type, Provider, Logger, DynamicModule, MessageEvent, OnModuleInit, OnApplicationShutdown } from '@nestjs/common';
|
|
1
|
+
import { ModuleMetadata, Type, Abstract, Provider, Logger, DynamicModule, MessageEvent, OnModuleInit, OnApplicationShutdown } from '@nestjs/common';
|
|
2
2
|
import { Subject, Observable } from 'rxjs';
|
|
3
3
|
import { Redis } from 'ioredis';
|
|
4
4
|
|
|
@@ -121,6 +121,16 @@ interface ConnectionEventMeta {
|
|
|
121
121
|
readonly connectionId: string;
|
|
122
122
|
readonly userId: string;
|
|
123
123
|
readonly tenantId: string | undefined;
|
|
124
|
+
/**
|
|
125
|
+
* Roles the authenticator returned for this connection, as a snapshot taken at
|
|
126
|
+
* connect time — `undefined` when the authenticator returned none.
|
|
127
|
+
*
|
|
128
|
+
* The library never interprets a role; it carries the consumer's own
|
|
129
|
+
* authorization vocabulary through so `onConnect` can act on it (typically by
|
|
130
|
+
* joining the connection to a role-scoped room). A later `revalidate` that
|
|
131
|
+
* keeps the connection alive does not refresh this snapshot.
|
|
132
|
+
*/
|
|
133
|
+
readonly roles: readonly string[] | undefined;
|
|
124
134
|
readonly transport: 'sse' | 'websocket';
|
|
125
135
|
readonly ip: string;
|
|
126
136
|
readonly userAgent: string | undefined;
|
|
@@ -324,8 +334,24 @@ interface BymaxRealtimeModuleAsyncOptions extends Pick<ModuleMetadata, 'imports'
|
|
|
324
334
|
* `transport` the factory resolves; a mismatch fails fast at bootstrap.
|
|
325
335
|
*/
|
|
326
336
|
transport: TransportMode;
|
|
327
|
-
|
|
328
|
-
|
|
337
|
+
/**
|
|
338
|
+
* Factory producing the options, receiving whatever `inject` resolves.
|
|
339
|
+
*
|
|
340
|
+
* Declared in method shorthand on purpose: that signature is bivariant, so a
|
|
341
|
+
* consumer can annotate the parameters with the real provider types
|
|
342
|
+
* (`(cfg: ConfigService) => ...`) instead of `unknown`. An arrow-property
|
|
343
|
+
* signature would be checked contravariantly under `strictFunctionTypes` and
|
|
344
|
+
* reject every typed factory, which is the whole point of `inject`.
|
|
345
|
+
*/
|
|
346
|
+
useFactory?(...args: unknown[]): BymaxRealtimeModuleOptions | Promise<BymaxRealtimeModuleOptions>;
|
|
347
|
+
/**
|
|
348
|
+
* Providers to resolve and pass to `useFactory`, positionally.
|
|
349
|
+
*
|
|
350
|
+
* `Abstract<unknown>` is included because Nest's own injectable tokens are
|
|
351
|
+
* abstract classes — `ModuleRef` among them — and `Type<unknown>` alone is a
|
|
352
|
+
* non-abstract constructor type that excludes them.
|
|
353
|
+
*/
|
|
354
|
+
inject?: readonly (string | symbol | Type<unknown> | Abstract<unknown>)[];
|
|
329
355
|
useExisting?: Type<BymaxRealtimeModuleOptionsFactory>;
|
|
330
356
|
useClass?: Type<BymaxRealtimeModuleOptionsFactory>;
|
|
331
357
|
/**
|
package/dist/internal/index.mjs
CHANGED
|
@@ -523,6 +523,7 @@ var SseTransport = class {
|
|
|
523
523
|
connectionId: record.connectionId,
|
|
524
524
|
userId: record.userId,
|
|
525
525
|
tenantId: record.tenantId,
|
|
526
|
+
roles: record.originalAuth.roles,
|
|
526
527
|
transport: "sse",
|
|
527
528
|
ip: record.ip,
|
|
528
529
|
userAgent: record.userAgent,
|
|
@@ -759,6 +760,7 @@ function buildMeta(record) {
|
|
|
759
760
|
connectionId: record.connectionId,
|
|
760
761
|
userId: record.userId,
|
|
761
762
|
tenantId: record.tenantId,
|
|
763
|
+
roles: record.originalAuth.roles,
|
|
762
764
|
transport: "sse",
|
|
763
765
|
ip: record.ip,
|
|
764
766
|
userAgent: record.userAgent,
|
|
@@ -1133,6 +1135,7 @@ var ReauthenticationService = class {
|
|
|
1133
1135
|
connectionId: conn.connectionId,
|
|
1134
1136
|
userId: conn.userId,
|
|
1135
1137
|
tenantId: conn.tenantId,
|
|
1138
|
+
roles: conn.originalAuth.roles,
|
|
1136
1139
|
transport: "sse",
|
|
1137
1140
|
ip: conn.ip,
|
|
1138
1141
|
userAgent: conn.userAgent,
|
package/dist/websocket/index.cjs
CHANGED
|
@@ -118,6 +118,7 @@ exports.WebSocketTransport = class WebSocketTransport {
|
|
|
118
118
|
connectionId: socket.id,
|
|
119
119
|
userId: auth.userId,
|
|
120
120
|
tenantId: auth.tenantId,
|
|
121
|
+
roles: auth.roles,
|
|
121
122
|
transport: "websocket",
|
|
122
123
|
ip: socket.handshake.address,
|
|
123
124
|
userAgent: socket.handshake.headers["user-agent"],
|
|
@@ -142,6 +143,7 @@ exports.WebSocketTransport = class WebSocketTransport {
|
|
|
142
143
|
connectionId,
|
|
143
144
|
userId: record.userId,
|
|
144
145
|
tenantId: record.tenantId,
|
|
146
|
+
roles: record.originalAuth.roles,
|
|
145
147
|
transport: "websocket",
|
|
146
148
|
ip: record.ip,
|
|
147
149
|
userAgent: record.userAgent,
|
package/dist/websocket/index.mjs
CHANGED
|
@@ -116,6 +116,7 @@ var WebSocketTransport = class {
|
|
|
116
116
|
connectionId: socket.id,
|
|
117
117
|
userId: auth.userId,
|
|
118
118
|
tenantId: auth.tenantId,
|
|
119
|
+
roles: auth.roles,
|
|
119
120
|
transport: "websocket",
|
|
120
121
|
ip: socket.handshake.address,
|
|
121
122
|
userAgent: socket.handshake.headers["user-agent"],
|
|
@@ -140,6 +141,7 @@ var WebSocketTransport = class {
|
|
|
140
141
|
connectionId,
|
|
141
142
|
userId: record.userId,
|
|
142
143
|
tenantId: record.tenantId,
|
|
144
|
+
roles: record.originalAuth.roles,
|
|
143
145
|
transport: "websocket",
|
|
144
146
|
ip: record.ip,
|
|
145
147
|
userAgent: record.userAgent,
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@bymax-one/nest-realtime",
|
|
3
|
-
"version": "1.1.
|
|
3
|
+
"version": "1.1.1",
|
|
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",
|
|
@@ -187,7 +187,7 @@
|
|
|
187
187
|
"eslint-plugin-prettier": "^5.0.0",
|
|
188
188
|
"eslint-plugin-react-hooks": "^7.1.1",
|
|
189
189
|
"eslint-plugin-security": "^4.0.1",
|
|
190
|
-
"eventsource": "^
|
|
190
|
+
"eventsource": "^5.1.0",
|
|
191
191
|
"ioredis": "^6.0.0",
|
|
192
192
|
"ioredis-mock": "^8.0.0",
|
|
193
193
|
"jest": "^30.0.0",
|