@bymax-one/nest-realtime 1.2.18 → 1.2.20

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/CHANGELOG.md CHANGED
@@ -7,6 +7,62 @@ 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
+
26
+ ## [1.2.19] - 2026-11-20
27
+
28
+ ### Added
29
+
30
+ - **Observability, all optional: metrics, a health indicator, spans and log events with stable codes.** A new subpath, `@bymax-one/nest-realtime/observability`, exports `RealtimeMetrics` and `RealtimePubSubHealthIndicator`. Registered as providers of a module of the application, `RealtimeMetrics` publishes `bymax_realtime_connections{transport}`, `bymax_realtime_connections_refused_total{reason}`, `bymax_realtime_evictions_total{reason}`, `bymax_realtime_events_emitted_total{transport}` and `bymax_realtime_slow_consumer_drops_total`, every label from a closed set, and the indicator reports `down` when the bus says it is not subscribed. With `@opentelemetry/api` installed, the library starts `realtime.handshake` and `realtime.reauthenticate` spans, and with no SDK registered they are no-ops. The root and the shared runtime import none of `@bymax-one/nest-core`, `prom-client` or `@opentelemetry/api` statically, which are optional peers, and `pnpm size` fails if one of them reaches those bundles. The README has the Metrics table, the Traces and Health notes and a Log events table.
31
+
32
+ ### Changed
33
+
34
+ - **Every `warn` and `error` line is an object with a stable code.** The line is `{ event: 'REALTIME_<EVENT>', message, ...fields }`, so a structured logger writes each as a JSON field and Nest's default logger prints the object instead of a sentence. The message text no longer names a user, a tenant, a room, a channel or a socket: those values were removed from the text, and the logger's own context carries identity. A connection id may be a field. A line that says the library started stays a string.
35
+ - **`bymax_realtime_events_emitted_total` is described as what it counts.** It counts emit calls handled on the instance, including a call with no recipient, and under `'both'` each transport counts it. The metric help text and the README say so.
36
+
37
+ #### Apply to a derived backend
38
+
39
+ An alert or a log filter that matched the text of a `warn` or `error` line now matches the `event` field instead; the codes are in the README. A host that parsed a line for a user, tenant, room or channel will not find it. Metrics start only when the application registers `RealtimeMetrics`, and spans only when it installs `@opentelemetry/api`; without them nothing changes. A class that subclasses `SseTransport`, `SseSubscriptionHandler`, `WebSocketTransport`, `RealtimeGateway` or `ReauthenticationService` and builds it by hand gains optional trailing constructor parameters and keeps working without them.
40
+
41
+ ### Fixed
42
+
43
+ - **Inputs were accepted, or failed as a raw `TypeError`, where a typed refusal belongs.** The `sseEndpoint` of `forRootAsync` was not covered by the check `sse.endpoint` got: a number failed as `endpoint.startsWith is not a function` and a blank one registered and served no route. A `forRoot` or `forRootAsync` called with no options, `null`, a string, a number or an array failed as "Cannot convert undefined or null to object", or as a message about `options.transport`; a factory that answered a string or a number was read the same way. A `Date` was accepted as `sse`, `websocket`, `reauthenticationPolicy` or `hooks`, because it is not an array. `new RedisOfflineQueue(undefined)` threw a raw `TypeError` and a string was accepted with no `client`. An endpoint with a space in it, `' /x '` or `'/a b'`, was registered and unreachable. Each of those is now refused with `REALTIME_INVALID_OPTIONS`, naming the option and what it received (`a built-in object` for a `Date`, a `Map` and the like). A `forRootAsync` pattern (`useFactory`, `useClass` or `useExisting`) set to `null` now reads as unset, like `undefined`: beside the pattern in use it is no longer counted as a second one, and alone it is refused at registration instead of failing at bootstrap with the container's own error.
44
+ - **A handshake that failed with an unexpected error counted in no metric, a `useExisting` that resolved to nothing failed with a raw `TypeError`, a proxy whose reads throw reached the application with its own error, and the cache warning was written before the logger was in place.** A 500 handshake now counts under `bymax_realtime_connections_refused_total{reason="error"}`. A `useExisting` or `useClass` provider with no `createRealtimeOptions` is refused with `REALTIME_INVALID_OPTIONS` at bootstrap. A proxy whose reads throw, given as the options or as a group, is refused as `a built-in object`. `REALTIME_REAUTH_CACHE_WEAKENS_POLICY` is written when the re-authentication service starts, through the application's logger, and no longer at registration.
45
+
46
+ #### Apply to a derived backend
47
+
48
+ A `sseEndpoint` or `sse.endpoint` that held whitespace, an options argument or factory result that was not an object, and a group that was a `Date` or another built-in now fail at registration, where they used to start or fail later: fix the value. A `RedisOfflineQueue` built without options or without a `client` now throws at construction. An instance of your own class is still read as a group by its keys, unless it sets its own `Symbol.toStringTag` to something other than `'Object'`.
49
+
50
+ A dashboard that sums `bymax_realtime_connections_refused_total` over its labels now includes `reason="error"`. A log pipeline that found `REALTIME_REAUTH_CACHE_WEAKENS_POLICY` at registration finds it at start-up, after `app.useLogger`, and only when the authenticator implements `revalidate`.
51
+
52
+ ### Security
53
+
54
+ - **A log line no longer carries the text of an error raised by the application's own code.** Events such as `REALTIME_HANDSHAKE_FAILED`, `REALTIME_HOOK_FAILED`, `REALTIME_DELIVERY_FAILED`, `REALTIME_DISCONNECT_FAILED`, `REALTIME_OFFLINE_QUEUE_ACK_FAILED`, `REALTIME_PUBSUB_UNSUBSCRIBE_FAILED`, `REALTIME_REAUTH_FAILED`, `REALTIME_REVOCATION_FAILED`, `REALTIME_COMPOSITE_PARTIAL_FAILURE`, `REALTIME_PUBSUB_UNAVAILABLE` put the error's own message into `message`, so an authenticator or a hook that threw `x user=U tenant=T` reached the line. `message` now holds the library's own text only, and the error goes under `err` as the error itself, which is where a structured logger applies its serializer and its redaction. A spec reads every `logEvent` call and fails when a message reads an error.
55
+
56
+ #### Apply to a derived backend
57
+
58
+ An alert, a filter or a dashboard that matched the text of an application error in the `message` of one of those events must read the `err` field instead. A custom `LoggerService` that turns a log argument into a string prints the object, including `err`; give it the object, or serialize `err` in it.
59
+
60
+ ### Documentation
61
+
62
+ - **The README names every export of every public subpath.** A spec now fails when a name in the public-surface snapshot, or one of the contract members an implementor writes, is missing from it. The README gained a Types and constants section and the Observability section.
63
+ - **The README says what a duplicate `socket.io` does.** Two copies in `node_modules` make TypeScript report TS2416 on `RealtimeIoAdapter` under `skipLibCheck: false`; the fix is one copy.
64
+ - **The README names the `./internal` exports and `ITransport.kind`, and a spec holds it.** The spec that fails when a public export is not named now covers the names `./internal` exports explicitly. The README also says that `./observability` needs its optional peers, and that without them the import fails with the runtime's own `Cannot find module` error, which names the peer.
65
+
10
66
  ## [1.2.18] - 2026-11-17
11
67
 
12
68
  ### Security
@@ -1163,7 +1219,9 @@ First published release.
1163
1219
  rather than by the manual sweep that raised the NestJS floors — that sweep
1164
1220
  asked about NestJS and never put the same question to the other ten peers.
1165
1221
 
1166
- [Unreleased]: https://github.com/bymaxone/nest-realtime/compare/v1.2.18...HEAD
1222
+ [Unreleased]: https://github.com/bymaxone/nest-realtime/compare/v1.2.20...HEAD
1223
+ [1.2.20]: https://github.com/bymaxone/nest-realtime/compare/v1.2.19...v1.2.20
1224
+ [1.2.19]: https://github.com/bymaxone/nest-realtime/compare/v1.2.18...v1.2.19
1167
1225
  [1.2.18]: https://github.com/bymaxone/nest-realtime/compare/v1.2.17...v1.2.18
1168
1226
  [1.2.17]: https://github.com/bymaxone/nest-realtime/compare/v1.2.16...v1.2.17
1169
1227
  [1.2.16]: https://github.com/bymaxone/nest-realtime/compare/v1.2.15...v1.2.16
package/README.md CHANGED
@@ -82,14 +82,15 @@ The default transport is **Server-Sent Events**: browser-native, plain HTTP, no
82
82
 
83
83
  ## 📦 Subpath Exports
84
84
 
85
- One package, four entry points — import only what your app needs:
85
+ One package, several entry points — import only what your app needs:
86
86
 
87
- | Subpath | Import | Purpose | Dependencies |
88
- | ------------- | ------------------------------------ | ---------------------------------------------- | :---------------------------------------------------------------: |
89
- | **Server** | `@bymax-one/nest-realtime` | NestJS module for SSE, services, contracts | NestJS 11, rxjs |
90
- | **WebSocket** | `@bymax-one/nest-realtime/websocket` | NestJS module for `'websocket'` and `'both'` | + `@nestjs/websockets`, `@nestjs/platform-socket.io`, `socket.io` |
91
- | **Shared** | `@bymax-one/nest-realtime/shared` | Types, room prefixes, event names, error codes | None |
92
- | **React** | `@bymax-one/nest-realtime/react` | Hooks & `RealtimeProvider` | React 19 |
87
+ | Subpath | Import | Purpose | Dependencies |
88
+ | ----------------- | ---------------------------------------- | ---------------------------------------------- | :---------------------------------------------------------------: |
89
+ | **Server** | `@bymax-one/nest-realtime` | NestJS module for SSE, services, contracts | NestJS 11, rxjs |
90
+ | **WebSocket** | `@bymax-one/nest-realtime/websocket` | NestJS module for `'websocket'` and `'both'` | + `@nestjs/websockets`, `@nestjs/platform-socket.io`, `socket.io` |
91
+ | **Shared** | `@bymax-one/nest-realtime/shared` | Types, room prefixes, event names, error codes | None |
92
+ | **React** | `@bymax-one/nest-realtime/react` | Hooks & `RealtimeProvider` | React 19 |
93
+ | **Observability** | `@bymax-one/nest-realtime/observability` | Metrics contributor, pub/sub health indicator | + `@bymax-one/nest-core`, `prom-client` (optional) |
93
94
 
94
95
  ```
95
96
  shared (zero deps)
@@ -103,6 +104,8 @@ One package, four entry points — import only what your app needs:
103
104
 
104
105
  The package also exposes `@bymax-one/nest-realtime/internal`. It is **not public API** and carries no compatibility promise — it is the shared runtime the two server subpaths import so that a service registered through one and injected through the other is the same class. Import the four above; nothing you need is only there.
105
106
 
107
+ These names from `./internal`, none of them API and none with a compatibility promise, are grouped below. Composition: `composeForRoot`, `composeForRootAsync`, `TransportRegistration`, `TransportWiring` and `sseWiring`. Shared services: `EventIdGenerator`, `ReauthenticationService`, `AuthenticationGate`, `AuthenticationUnavailableError`, `ConnectionAdmission`, `ConnectionLimitError`, `UNBOUNDED_TICKET`, `AdmissionTicket`, `OfflineQueueDeliveryService`, `EventReplayBuffer`, `HeartbeatService`, `SseSubscriptionHandler`, `createSseController`, `RoomRegistry`, `SseTransport` and `RealtimePubSubSubscriber`. Observability seams: `RealtimeMetricsTally`, `REFUSAL_REASONS`, `EVICTION_REASONS`, `TALLY_TRANSPORTS`, `RefusalReason`, `EvictionReason`, `TallyTransport`, `RealtimeTracing`, `RealtimeSpanName`, `RealtimeSpanAttributes`, `logEvent`, `REALTIME_LOG_EVENTS`, `RealtimeLogEvent` and `LogFields`. Utilities: `DEFAULT_HOOK_TIMEOUT_MS`, `assertIdentityIsNotBlank`, `resolveAuthTenant`, `admitRooms`, `describeError`, `quitWithin`, `QuitableClient`, `runHook`, `unavailableError`, `refuseReservedRoom`, `requireRoomName`, `realtimeError`, `CodedError`, `reportDeliveryFailure` and `parseCookieHeader`.
108
+
106
109
  ---
107
110
 
108
111
  > [!TIP]
@@ -284,7 +287,7 @@ For WebSocket, scaling goes through Socket.IO's own Redis adapter instead, confi
284
287
 
285
288
  ### 7. Add WebSocket (optional)
286
289
 
287
- WebSocket lives behind its own subpath, so an SSE application never installs the Socket.IO stack. Install its peers (see [Install](#1-install)), then do two things: register `BymaxRealtimeWebSocketModule` from `/websocket` instead of `BymaxRealtimeModule`, and install `RealtimeIoAdapter` in `main.ts`.
290
+ WebSocket lives behind its own subpath, so an SSE application never installs the Socket.IO stack. Install its peers (see [Install](#1-install)), then do two things: register `BymaxRealtimeWebSocketModule` from `/websocket` instead of `BymaxRealtimeModule`, and install `RealtimeIoAdapter` in `main.ts`. Two copies of `socket.io` in `node_modules` make TypeScript report TS2416 on `RealtimeIoAdapter` under `skipLibCheck: false`; dedupe to one copy.
288
291
 
289
292
  ```typescript
290
293
  // app.module.ts
@@ -407,9 +410,9 @@ An SSE response writes one event at a time and waits for the client to read befo
407
410
 
408
411
  An option that holds `undefined` or `null` is read as unset: it takes its default, in the module options and in `sse`, `websocket` and `reauthenticationPolicy`, so `maxConnectionsPerUser: cond ? 3 : undefined` means the default cap of `5`, never no cap. Say `0` where `0` switches a bound off. A refusal of an option names the option and the type of what it received (`received a string`), prints a finite number, and echoes nothing else, so a value pasted into the wrong field does not reach a log.
409
412
 
410
- 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.
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.
411
414
 
412
- 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`.
413
416
 
414
417
  > [!IMPORTANT]
415
418
  > **`forRootAsync` takes the SSE route on the registration, not from the factory.** NestJS
@@ -475,6 +478,65 @@ This section lists the bounds the library applies, what happens when each one is
475
478
 
476
479
  The Socket.IO server closes first, then the adapter's `dispose()` runs, and `dispose()` closes the adapter's own Redis subscriber connection. The pub/sub subscriber is unsubscribed in the application shutdown hook. When both transports run, the two Redis subscribers are closed in two successive phases, each waited for at most 2,000 ms. [Shutdown](#shutdown) describes how a shutdown starts.
477
480
 
481
+ ### Observability
482
+
483
+ Everything here is optional. The root and the shared runtime import none of `@bymax-one/nest-core`, `prom-client` or `@opentelemetry/api` statically, so an application that publishes no metrics installs none of them.
484
+
485
+ Importing `@bymax-one/nest-realtime/observability` needs `@bymax-one/nest-core` and `prom-client`; without them the import fails with the runtime's own `Cannot find module` error, which names the missing peer.
486
+
487
+ **Metrics.** Register `RealtimeMetrics` in a module of your application; `BymaxCoreModule` discovers it and calls it once at bootstrap with the registry its scrape endpoint serves. It injects what the realtime module exports, so nothing else is wired.
488
+
489
+ ```typescript
490
+ import { Module } from '@nestjs/common'
491
+ import {
492
+ RealtimeMetrics,
493
+ RealtimePubSubHealthIndicator,
494
+ } from '@bymax-one/nest-realtime/observability'
495
+
496
+ @Module({ providers: [RealtimeMetrics, RealtimePubSubHealthIndicator] })
497
+ export class ObservabilityModule {}
498
+ ```
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. |
507
+
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
+
510
+ **Health.** `RealtimePubSubHealthIndicator` (name `realtime-pubsub`) reports `down` when the bus says it is not subscribed, so what other instances publish no longer reaches this one. It reads the bus's own state, sends nothing and returns no detail. A bus that does not report its state, such as the in-memory one, counts as up.
511
+
512
+ **Traces.** With `@opentelemetry/api` installed the library starts `realtime.handshake` around the admission and authentication of each connection (attribute `bymax.realtime.transport`, `sse` or `websocket`) and `realtime.reauthenticate` around each re-authentication cycle. A refused handshake ends its span with status ERROR and the library error code, never the message. With no SDK registered the API is a no-op, and without the package nothing is started.
513
+
514
+ **Log events.** Every `warn` and `error` line the library writes is an object, `{ event, message, ...fields }`, with the error that caused a failure, when there is one, under `err` as the error itself and never as text in `message`; so a structured logger writes each as a JSON field and Nest's default logger prints the object. The fields are counts, sizes, configured limits, transport names and a library-made connection id; a user id, a tenant id or a room is never in a message or a field, because the logger's own context carries identity. Lines that report that the library started stay plain strings.
515
+
516
+ | Event | Level | When | Fields |
517
+ | -------------------------------------- | ----------- | ----------------------------------------------------------------------------------- | ------------------------------------------------------------------------ |
518
+ | `REALTIME_REAUTH_CACHE_WEAKENS_POLICY` | warn | At start-up, `reauthenticationPolicy.cacheTtlMs` is longer than the interval. | `cacheTtlMs`, `intervalMs` |
519
+ | `REALTIME_HANDSHAKE_FAILED` | error | A handshake failed with an error that is not a refusal. | `socketId` (WebSocket) |
520
+ | `REALTIME_HOOK_FAILED` | warn, error | A lifecycle hook threw or did not settle within `hookTimeoutMs`. | `hook` where known |
521
+ | `REALTIME_DELIVERY_FAILED` | warn | A delivery failed without failing its call. | `connectionId` or `code`, `op` |
522
+ | `REALTIME_SLOW_CONSUMER` | warn | A connection was cut for not reading what it was sent. | `connectionId`, `queuedEvents`, `queuedBytes`, `heldBytes` |
523
+ | `REALTIME_DISCONNECT_FAILED` | warn | Closing a connection failed. | `connectionId` |
524
+ | `REALTIME_RECONNECTS_GIVEN_UP` | warn | Reconnects were given up on because the offline queue did not answer (windowed). | `count`, `timeoutMs`, `maxPending` |
525
+ | `REALTIME_OFFLINE_QUEUE_LIMIT` | warn | A read of the offline queue reached its event limit. | `limit` |
526
+ | `REALTIME_OFFLINE_QUEUE_ACK_FAILED` | warn | Acknowledging the offline queue failed. | none |
527
+ | `REALTIME_PUBSUB_NOT_PROVIDED` | warn | In production, no `IRealtimePubSub` was provided: single instance only. | none |
528
+ | `REALTIME_PUBSUB_UNSUBSCRIBE_FAILED` | warn | Unsubscribing from the bus failed at shutdown. | none |
529
+ | `REALTIME_PUBSUB_DROPPED` | warn | The bus dropped messages it could not act on (windowed). | `count`, `last` |
530
+ | `REALTIME_PUBSUB_UNAVAILABLE` | warn | The bus refused or lost the subscription; remote events do not reach this instance. | none |
531
+ | `REALTIME_CONNECTIONS_REFUSED` | warn | Connections were refused at `maxConnections` (windowed). | `count`, `maxConnections` |
532
+ | `REALTIME_HANDSHAKES_REFUSED` | warn | Handshakes were refused because the authenticator was saturated or slow (windowed). | `saturated`, `timedOut`, `maxPendingHandshakes`, `authenticateTimeoutMs` |
533
+ | `REALTIME_REAUTH_FAILED` | warn | A re-authentication cycle, a check or its notification failed. | `connectionId` where known |
534
+ | `REALTIME_REVOCATION_FAILED` | warn | A revocation failed and is retried on the next cycle. | `connectionId` |
535
+ | `REALTIME_ADAPTER_MISSING` | error | `RealtimeIoAdapter` is not the active WebSocket adapter. | none |
536
+ | `REALTIME_ADAPTER_COMMAND_FAILED` | warn | A command of the Redis adapter's subscriber failed (once for each connection). | none |
537
+ | `REALTIME_COMPOSITE_PARTIAL_FAILURE` | warn | One of the two transports failed an emit under `transport: 'both'`. | `op` |
538
+ | `REALTIME_SERVER_NOT_ATTACHED` | warn | An emit was made before the WebSocket server was attached (once). | `op` |
539
+
478
540
  ### Before you deploy
479
541
 
480
542
  - File-descriptor limit against `maxConnections`: [How many connections one instance holds](#how-many-connections-one-instance-holds).
@@ -795,6 +857,9 @@ proxy it is the proxy's address. Use it to decide whether a forwarded header suc
795
857
  `undefined` when the socket reports no address, and an IPv4 peer can arrive in its IPv4-mapped form
796
858
  (`::ffff:10.0.0.1`), which is passed through as reported.
797
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
+
798
863
  ### Rooms
799
864
 
800
865
  | Room ID | Used for | Auto-joined |
@@ -931,6 +996,25 @@ From the `onModuleDestroy` phase on, which runs ahead of every `beforeApplicatio
931
996
 
932
997
  A client that stopped reading holds its socket open after the library has ended its stream, and Node's HTTP server waits for it: `app.close()` took 6,004 ms with such clients and 3 ms with `forceCloseConnections: true`. Create the application with `NestFactory.create(AppModule, { forceCloseConnections: true })`, or give the process a termination grace of at least 7 seconds.
933
998
 
999
+ ### Types and constants
1000
+
1001
+ Every name below is exported; the subpath says where to import it from. A type is erased at run time, a constant is a value.
1002
+
1003
+ **Options.** `BymaxRealtimeModuleOptions` is the configuration of `forRoot`, and `BymaxRealtimeModuleAsyncOptions` that of `forRootAsync` (`useFactory`, `useClass`, `useExisting`, `inject`, `imports`, `sseEndpoint` and `extraProviders`, the providers to register beside the module, for instance an authenticator class that Nest manages). `SseOptions` and `WebSocketOptions` are the `sse` and `websocket` groups, `ReauthenticationPolicy` is `reauthenticationPolicy`, and `CorsConfig` is the CORS configuration both transports share. `RedisOfflineQueueOptions` and `RedisRealtimePubSubOptions` configure the two Redis implementations that ship with the package.
1004
+
1005
+ **What a hook or an authenticator receives.** `AuthenticatorCallOptions` is what `authenticate` and `revalidate` are handed besides their subject. `DeliveryFailure` is what `onDeliveryFailure` receives when a delivery path failed without failing the call that depended on it. `PublicConnectionMeta` is the public-facing metadata of one connection.
1006
+
1007
+ **Events and rooms** (from `@bymax-one/nest-realtime/shared`). `RealtimeEvent` is the shape of an event over a transport (`id`, `type` and `data`) and `ReservedEventName` the union of the names the library reserves. `ROOM_PREFIXES` is the table of canonical room prefixes and `RoomPrefix` the union of its values. `TransportMode` is `'sse' | 'websocket' | 'both'`. `REALTIME_ERROR_CODES` is the table of the stable error codes, such as `REALTIME_AUTH_FAILED`.
1008
+
1009
+ **Queues and the bus.** `OfflineQueuedEvent` is one event held in a user's offline queue, and `RealtimePubSubMessage` is one message that crosses instances.
1010
+
1011
+ **Members of the contracts you implement.**
1012
+
1013
+ - `IOfflineQueueStorage`: `append` stores an event for a user, `retrieveSince` reads the ones after an id, and `acknowledge` marks events delivered up to an id, which an implementation may purge or keep.
1014
+ - `IPresenceStorage`: `setOnline` and `setOffline` record a connection, `isOnline` answers for a user, `listOnlineByTenant` lists a tenant's online users and `countOnline` counts everyone.
1015
+ - `IRealtimePubSub`: `publish` sends to the other instances, `subscribe` receives, and the optional `isSubscribed` says whether this instance is subscribed now. A bus that cannot be unsubscribed once subscribed omits it and counts as subscribed; the health indicator reads it.
1016
+ - `ITransport`: `kind` names the transport, `'sse'` or `'websocket'`; the optional `onModuleInit`, `beforeApplicationShutdown` and `onApplicationShutdown` are called by Nest on bootstrap and on shutdown, the second before the HTTP server closes.
1017
+
934
1018
  ### DI Tokens
935
1019
 
936
1020
  `REALTIME_OPTIONS_TOKEN` · `REALTIME_TRANSPORT_TOKEN` · `REALTIME_AUTHENTICATOR_TOKEN` · `REALTIME_PUBSUB_TOKEN` · `REALTIME_OFFLINE_QUEUE_TOKEN` · `REALTIME_PRESENCE_TOKEN` · `REALTIME_HOOKS_TOKEN` · `REALTIME_INSTANCE_ID_TOKEN`