@bymax-one/nest-realtime 1.2.5 → 1.2.7
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/CHANGELOG.md +135 -1
- package/README.md +87 -53
- package/dist/internal/index.cjs +370 -77
- package/dist/internal/index.d.cts +221 -51
- package/dist/internal/index.d.ts +221 -51
- package/dist/internal/index.mjs +369 -78
- package/dist/server/index.d.cts +1 -1
- package/dist/server/index.d.ts +1 -1
- package/dist/shared/index.cjs +1 -0
- package/dist/shared/index.d.cts +1 -0
- package/dist/shared/index.d.ts +1 -0
- package/dist/shared/index.mjs +1 -0
- package/dist/websocket/index.cjs +76 -24
- package/dist/websocket/index.d.cts +30 -11
- package/dist/websocket/index.d.ts +30 -11
- package/dist/websocket/index.mjs +77 -25
- package/package.json +2 -1
|
@@ -54,16 +54,18 @@ interface ConnectionAuthContext {
|
|
|
54
54
|
*/
|
|
55
55
|
readonly query: Record<string, string | string[] | undefined>;
|
|
56
56
|
/**
|
|
57
|
-
* Client IP
|
|
58
|
-
*
|
|
59
|
-
*
|
|
57
|
+
* Client IP. On SSE it is the address the application's `trust proxy` setting produced
|
|
58
|
+
* (`req.ip`, else the nearest trusted hop, else the socket peer), so `X-Forwarded-For` is
|
|
59
|
+
* believed only as far as that setting reaches and is never read directly. On WebSocket
|
|
60
|
+
* it is the handshake's peer address, which behind a proxy is the proxy's. `''` when no
|
|
61
|
+
* channel carries an address; a header text that is not an address is never returned.
|
|
60
62
|
*/
|
|
61
63
|
readonly ip: string;
|
|
62
64
|
/**
|
|
63
65
|
* The TCP peer address of the connection: the socket's own `remoteAddress`, never read
|
|
64
66
|
* from a header, so a client cannot forge it. It is the proxy's address when one sits
|
|
65
|
-
* in front of the application, and it is distinct from `ip`, which on SSE
|
|
66
|
-
* `
|
|
67
|
+
* in front of the application, and it is distinct from `ip`, which on SSE follows the
|
|
68
|
+
* application's `trust proxy` setting. Use it to decide whether a forwarded header such as
|
|
67
69
|
* `X-Forwarded-Host` may be believed, by checking it against the proxies you trust.
|
|
68
70
|
*
|
|
69
71
|
* `undefined` when the socket reports no address. A peer on IPv4 can arrive in its
|
|
@@ -152,10 +154,55 @@ interface IConnectionAuthenticator {
|
|
|
152
154
|
revalidate?(connectionId: string, originalAuth: AuthenticationResult): Promise<boolean>;
|
|
153
155
|
}
|
|
154
156
|
|
|
157
|
+
/**
|
|
158
|
+
* @fileoverview Canonical error codes emitted by the library (the §14 catalog).
|
|
159
|
+
* @layer shared
|
|
160
|
+
*/
|
|
161
|
+
/**
|
|
162
|
+
* Canonical error codes emitted by the library. Map 1-to-1 with
|
|
163
|
+
* `docs/technical_specification.md` §14.
|
|
164
|
+
*
|
|
165
|
+
* `TOO_MANY_CONNECTIONS` signals FIFO eviction: when a user exceeds
|
|
166
|
+
* `maxConnectionsPerUser`, the OLDEST connection is evicted (closed with this
|
|
167
|
+
* code) and the new one is admitted — it is never an HTTP 429 rejection.
|
|
168
|
+
*/
|
|
169
|
+
declare const REALTIME_ERROR_CODES: {
|
|
170
|
+
readonly INVALID_OPTIONS: "REALTIME_INVALID_OPTIONS";
|
|
171
|
+
readonly NO_AUTHENTICATOR: "REALTIME_NO_AUTHENTICATOR";
|
|
172
|
+
readonly AUTH_FAILED: "REALTIME_AUTH_FAILED";
|
|
173
|
+
readonly REAUTHENTICATION_FAILED: "REALTIME_REAUTHENTICATION_FAILED";
|
|
174
|
+
readonly TOO_MANY_CONNECTIONS: "REALTIME_TOO_MANY_CONNECTIONS";
|
|
175
|
+
readonly INVALID_TICKET: "REALTIME_INVALID_TICKET";
|
|
176
|
+
readonly PUBSUB_UNAVAILABLE: "REALTIME_PUBSUB_UNAVAILABLE";
|
|
177
|
+
readonly TRANSPORT_UNAVAILABLE: "REALTIME_TRANSPORT_UNAVAILABLE";
|
|
178
|
+
readonly REDIS_ADAPTER_FAILED: "REALTIME_REDIS_ADAPTER_FAILED";
|
|
179
|
+
readonly PAYLOAD_TOO_LARGE: "REALTIME_PAYLOAD_TOO_LARGE";
|
|
180
|
+
readonly REPLAY_BUFFER_MISS: "REALTIME_REPLAY_BUFFER_MISS";
|
|
181
|
+
};
|
|
182
|
+
/** Union of canonical error code values. */
|
|
183
|
+
type RealtimeErrorCode = (typeof REALTIME_ERROR_CODES)[keyof typeof REALTIME_ERROR_CODES];
|
|
184
|
+
|
|
155
185
|
/**
|
|
156
186
|
* @fileoverview Optional connection lifecycle hooks the consumer can provide.
|
|
157
187
|
* @layer contracts
|
|
158
188
|
*/
|
|
189
|
+
|
|
190
|
+
/**
|
|
191
|
+
* A delivery path that failed without failing the call that depended on it, such as an emit
|
|
192
|
+
* whose publish to the other instances was refused. The call still resolved; this is how the
|
|
193
|
+
* failure becomes visible.
|
|
194
|
+
*/
|
|
195
|
+
interface DeliveryFailure {
|
|
196
|
+
/** The stable error code of the failure. */
|
|
197
|
+
readonly code: RealtimeErrorCode;
|
|
198
|
+
/**
|
|
199
|
+
* What was being delivered: an emit (`emitToUser`, `emitToTenant`, `emitToRoom`,
|
|
200
|
+
* `broadcast`) or `offlineAppend` / `offlineRetrieve` for the offline queue.
|
|
201
|
+
*/
|
|
202
|
+
readonly op: string;
|
|
203
|
+
/** The failure underneath. */
|
|
204
|
+
readonly error: Error;
|
|
205
|
+
}
|
|
159
206
|
/** Metadata describing a connection at a lifecycle transition. */
|
|
160
207
|
interface ConnectionEventMeta {
|
|
161
208
|
readonly connectionId: string;
|
|
@@ -225,6 +272,12 @@ interface IConnectionLifecycleHooks {
|
|
|
225
272
|
}): void | Promise<void>;
|
|
226
273
|
/** Called on re-authentication failure, before disconnect. */
|
|
227
274
|
onReauthenticationFailed?(meta: ConnectionEventMeta): void | Promise<void>;
|
|
275
|
+
/**
|
|
276
|
+
* Called when a delivery path fails but the call that used it still resolves: the publish of an
|
|
277
|
+
* emit to the other instances, or the offline queue. Count it to see cross-instance loss; it
|
|
278
|
+
* is also logged with the same code. A throwing hook is logged and ignored.
|
|
279
|
+
*/
|
|
280
|
+
onDeliveryFailure?(failure: DeliveryFailure): void | Promise<void>;
|
|
228
281
|
}
|
|
229
282
|
|
|
230
283
|
/**
|
|
@@ -251,8 +304,20 @@ interface RealtimePubSubMessage {
|
|
|
251
304
|
interface IRealtimePubSub {
|
|
252
305
|
/** Publish a message to all subscribers (the other instances). */
|
|
253
306
|
publish(message: RealtimePubSubMessage): Promise<void>;
|
|
254
|
-
/**
|
|
307
|
+
/**
|
|
308
|
+
* Subscribe to messages. Resolves to an async unsubscribe handle.
|
|
309
|
+
*
|
|
310
|
+
* Rejects when the bus refuses the subscription for a reason no retry fixes (a wrong password,
|
|
311
|
+
* a missing permission), which fails the application's boot. A bus that cannot be reached yet
|
|
312
|
+
* may resolve and report itself through `isSubscribed`.
|
|
313
|
+
*/
|
|
255
314
|
subscribe(handler: (message: RealtimePubSubMessage) => void): Promise<() => Promise<void>>;
|
|
315
|
+
/**
|
|
316
|
+
* Whether this instance is subscribed right now, so the messages other instances publish reach
|
|
317
|
+
* it. Optional: a bus that cannot be unsubscribed once subscribed (the in-memory one) omits it
|
|
318
|
+
* and counts as subscribed.
|
|
319
|
+
*/
|
|
320
|
+
isSubscribed?(): boolean;
|
|
256
321
|
}
|
|
257
322
|
|
|
258
323
|
/**
|
|
@@ -770,7 +835,21 @@ interface ITransport {
|
|
|
770
835
|
*/
|
|
771
836
|
declare class RealtimeService {
|
|
772
837
|
private readonly transport;
|
|
773
|
-
|
|
838
|
+
private readonly pubsub?;
|
|
839
|
+
constructor(transport: ITransport, pubsub?: IRealtimePubSub | undefined);
|
|
840
|
+
/**
|
|
841
|
+
* Whether this instance hears the events and revocations other instances publish. False while
|
|
842
|
+
* the bus is unreachable or its subscriber connection is down, so a readiness probe can take a
|
|
843
|
+
* deaf instance out of rotation. True for a bus that does not report a state, and with
|
|
844
|
+
* `transport: 'websocket'`, which does not subscribe to the bus.
|
|
845
|
+
*
|
|
846
|
+
* @example
|
|
847
|
+
* ```ts
|
|
848
|
+
* // In a health indicator: `isHealthy` is false while the instance cannot hear the others.
|
|
849
|
+
* return indicator.check('realtime', realtime.isPubSubReady())
|
|
850
|
+
* ```
|
|
851
|
+
*/
|
|
852
|
+
isPubSubReady(): boolean;
|
|
774
853
|
/**
|
|
775
854
|
* Send to all of a user's connections (across devices/tabs).
|
|
776
855
|
*
|
|
@@ -795,11 +874,28 @@ declare class RealtimeService {
|
|
|
795
874
|
* The room id is not checked. Never pass client-supplied input that could start
|
|
796
875
|
* with the reserved `user:` or `tenant:` prefixes: joining `tenant:<other>`
|
|
797
876
|
* receives that tenant's events.
|
|
877
|
+
*
|
|
878
|
+
* Acts on a connection this instance holds; for any other id it resolves and changes
|
|
879
|
+
* nothing. A failure of the transport that holds the connection rejects the call.
|
|
798
880
|
*/
|
|
799
881
|
joinRoom(connectionId: string, roomId: string): Promise<void>;
|
|
800
|
-
/**
|
|
882
|
+
/**
|
|
883
|
+
* Remove a specific connection from a room.
|
|
884
|
+
*
|
|
885
|
+
* Acts on a connection this instance holds; for any other id it resolves and changes
|
|
886
|
+
* nothing. A failure of the transport that holds the connection rejects the call.
|
|
887
|
+
*/
|
|
801
888
|
leaveRoom(connectionId: string, roomId: string): Promise<void>;
|
|
802
|
-
/**
|
|
889
|
+
/**
|
|
890
|
+
* Force-disconnect a specific connection (e.g. on auth revocation).
|
|
891
|
+
*
|
|
892
|
+
* Resolves once the connection is closed on this instance or the revocation has been handed
|
|
893
|
+
* to the bus for the instance that holds it.
|
|
894
|
+
*
|
|
895
|
+
* @throws {Error} `REALTIME_PUBSUB_UNAVAILABLE` when the bus refuses the revocation, or
|
|
896
|
+
* `REALTIME_TRANSPORT_UNAVAILABLE` when the transport that holds the connection fails.
|
|
897
|
+
* The connection may still be connected: retry.
|
|
898
|
+
*/
|
|
803
899
|
disconnect(connectionId: string, reason?: string): Promise<void>;
|
|
804
900
|
}
|
|
805
901
|
|
|
@@ -855,6 +951,12 @@ declare class ReauthenticationService implements OnModuleInit, OnApplicationShut
|
|
|
855
951
|
* Exposed as public for test access.
|
|
856
952
|
*/
|
|
857
953
|
runCycle(): Promise<void>;
|
|
954
|
+
/**
|
|
955
|
+
* Revoke a connection whose revalidation failed, and keep the cycle going when the
|
|
956
|
+
* revocation itself is rejected. The positive-cache entry is already gone, so the next
|
|
957
|
+
* cycle revalidates the connection and tries again.
|
|
958
|
+
*/
|
|
959
|
+
private revoke;
|
|
858
960
|
/** Evict the positive-cache entry, optionally emit the failure event, then disconnect. */
|
|
859
961
|
private handleFailure;
|
|
860
962
|
}
|
|
@@ -897,8 +999,9 @@ declare class RoomRegistry {
|
|
|
897
999
|
*/
|
|
898
1000
|
declare class OfflineQueueDeliveryService {
|
|
899
1001
|
private readonly storage?;
|
|
1002
|
+
private readonly hooks?;
|
|
900
1003
|
private readonly logger;
|
|
901
|
-
constructor(storage?: IOfflineQueueStorage | undefined);
|
|
1004
|
+
constructor(storage?: IOfflineQueueStorage | undefined, hooks?: IConnectionLifecycleHooks | undefined);
|
|
902
1005
|
/**
|
|
903
1006
|
* Return events for `userId` that arrived after `lastEventId` and are NOT
|
|
904
1007
|
* already covered by `ringBufferIds` (already replayed from in-memory buffer).
|
|
@@ -1019,13 +1122,22 @@ interface SseRequest {
|
|
|
1019
1122
|
/**
|
|
1020
1123
|
* Request headers, keyed as the HTTP framework delivers them. Node lowercases
|
|
1021
1124
|
* incoming header names, and the endpoint looks them up lowercase — `cookie`,
|
|
1022
|
-
* `user-agent
|
|
1125
|
+
* `user-agent` and `last-event-id` — so an adapter that
|
|
1023
1126
|
* preserves the client's casing has to lowercase the keys before it gets here,
|
|
1024
1127
|
* or those lookups miss.
|
|
1025
1128
|
*/
|
|
1026
1129
|
readonly headers: Readonly<Record<string, SseHeaderValue>>;
|
|
1027
|
-
/**
|
|
1130
|
+
/**
|
|
1131
|
+
* Client address as the HTTP framework resolved it under the application's trusted-proxy
|
|
1132
|
+
* setting, when it resolves one. The endpoint validates it before using it.
|
|
1133
|
+
*/
|
|
1028
1134
|
readonly ip?: string | undefined;
|
|
1135
|
+
/**
|
|
1136
|
+
* The addresses behind `ip`, from the client end toward the socket, when the framework reports
|
|
1137
|
+
* them (Express and Fastify do under a trusted-proxy setting). Each entry after the first is a
|
|
1138
|
+
* hop that setting already vouched for.
|
|
1139
|
+
*/
|
|
1140
|
+
readonly ips?: readonly string[] | undefined;
|
|
1029
1141
|
/**
|
|
1030
1142
|
* The underlying connection, when the framework exposes it (Express and Fastify do as
|
|
1031
1143
|
* `req.socket`). Its `remoteAddress` is the TCP peer, unlike `ip`, which a trusted-proxy
|
|
@@ -1126,13 +1238,36 @@ declare class SseTransport implements ITransport {
|
|
|
1126
1238
|
* @returns The `ConnectionRecord`, or `undefined` when not found.
|
|
1127
1239
|
*/
|
|
1128
1240
|
getConnection(connectionId: string): ConnectionRecord | undefined;
|
|
1241
|
+
/**
|
|
1242
|
+
* Emit to a user: live here, to the other instances over the bus, and into the offline queue
|
|
1243
|
+
* when the user has no live connection on this instance.
|
|
1244
|
+
*
|
|
1245
|
+
* A failed publish or a failed append is reported (log and `onDeliveryFailure`) and the call
|
|
1246
|
+
* still resolves, since delivery to the other instances is at-most-once. It rejects only when
|
|
1247
|
+
* the event has no delivery path left: the user is offline here, the queue could not keep it,
|
|
1248
|
+
* and the bus either failed or cannot reach another instance (the in-memory bus). A rejection
|
|
1249
|
+
* carries the queue failure as its cause and is not also reported to the hook.
|
|
1250
|
+
*/
|
|
1129
1251
|
emitToUser(userId: string, event: string, data: unknown): Promise<void>;
|
|
1252
|
+
/** Append to the offline queue; resolves with the failure, or `undefined` once it is kept. */
|
|
1253
|
+
private tryAppend;
|
|
1254
|
+
/** Whether the bus can carry an event to another instance (the in-memory bus cannot). */
|
|
1255
|
+
private busReachesOtherInstances;
|
|
1130
1256
|
emitToTenant(tenantId: string, event: string, data: unknown): Promise<void>;
|
|
1131
1257
|
emitToRoom(roomId: string, event: string, data: unknown): Promise<void>;
|
|
1132
1258
|
broadcast(event: string, data: unknown): Promise<void>;
|
|
1259
|
+
/** Join a connection this instance holds to a room; any other id is left alone. */
|
|
1133
1260
|
joinRoom(connectionId: string, roomId: string): Promise<void>;
|
|
1261
|
+
/** Remove a connection this instance holds from a room; any other id is left alone. */
|
|
1134
1262
|
leaveRoom(connectionId: string, roomId: string): Promise<void>;
|
|
1135
|
-
/**
|
|
1263
|
+
/**
|
|
1264
|
+
* Disconnect a connection locally if owned here, otherwise revoke cross-instance.
|
|
1265
|
+
*
|
|
1266
|
+
* Resolves once the connection is closed here or the revocation has been handed to the bus. A
|
|
1267
|
+
* connection held here as a WebSocket is left to the WebSocket transport and nothing is
|
|
1268
|
+
* published. It rejects with `REALTIME_PUBSUB_UNAVAILABLE` when the bus refuses it: nothing has reached
|
|
1269
|
+
* the connection, so the caller must not read the resolution as a revocation.
|
|
1270
|
+
*/
|
|
1136
1271
|
disconnect(connectionId: string, reason?: string): Promise<void>;
|
|
1137
1272
|
/**
|
|
1138
1273
|
* Deliver an event to a user's local SSE connections and update the replay buffer.
|
|
@@ -1178,8 +1313,11 @@ declare class SseTransport implements ITransport {
|
|
|
1178
1313
|
private buildMessage;
|
|
1179
1314
|
/** Deliver to one connection, isolating failures so others still receive the event. */
|
|
1180
1315
|
private deliver;
|
|
1181
|
-
/** Publish once to the bus;
|
|
1316
|
+
/** Publish once to the bus; resolves with the failure, or `undefined` once the bus accepted it. */
|
|
1317
|
+
private tryPublish;
|
|
1318
|
+
/** Publish once to the bus. A failure is reported and never fails the live emit path. */
|
|
1182
1319
|
private publish;
|
|
1320
|
+
private reportPublishFailure;
|
|
1183
1321
|
/** Evict a user's oldest connections (FIFO) when over `maxConnectionsPerUser`. */
|
|
1184
1322
|
private evictBeyondLimit;
|
|
1185
1323
|
}
|
|
@@ -1347,8 +1485,9 @@ declare class InMemoryPubSub implements IRealtimePubSub {
|
|
|
1347
1485
|
* the transport's `*Local` methods, which deliver without re-publishing.
|
|
1348
1486
|
*
|
|
1349
1487
|
* Messages from this instance (echo) are dropped via the `origin` guard.
|
|
1350
|
-
*
|
|
1351
|
-
*
|
|
1488
|
+
* A subscribe that fails fails the boot: an instance that cannot hear the others would
|
|
1489
|
+
* miss every revocation. A bus that merely cannot be reached yet resolves its subscribe and
|
|
1490
|
+
* reports itself through `isSubscribed()` instead. An unsubscribe failure is logged.
|
|
1352
1491
|
*/
|
|
1353
1492
|
declare class RealtimePubSubSubscriber implements OnModuleInit, OnApplicationShutdown {
|
|
1354
1493
|
private readonly pubsub;
|
|
@@ -1362,11 +1501,6 @@ declare class RealtimePubSubSubscriber implements OnModuleInit, OnApplicationShu
|
|
|
1362
1501
|
private handle;
|
|
1363
1502
|
}
|
|
1364
1503
|
|
|
1365
|
-
/**
|
|
1366
|
-
* @fileoverview Redis-backed pub/sub for cross-instance SSE fan-out.
|
|
1367
|
-
* @layer infrastructure
|
|
1368
|
-
*/
|
|
1369
|
-
|
|
1370
1504
|
/** Options for RedisRealtimePubSub. */
|
|
1371
1505
|
interface RedisRealtimePubSubOptions {
|
|
1372
1506
|
/** The Redis client used for publishing. A separate subscriber clone is created internally. */
|
|
@@ -1381,7 +1515,14 @@ interface RedisRealtimePubSubOptions {
|
|
|
1381
1515
|
* `SUBSCRIBE` (a lazily-duplicated clone). The subscriber clone is created on
|
|
1382
1516
|
* the first `subscribe()` call and quit on the last `unsubscribe()`.
|
|
1383
1517
|
*
|
|
1384
|
-
* Messages are JSON-encoded.
|
|
1518
|
+
* Messages are JSON-encoded. A malformed payload is dropped and counted, and the count is
|
|
1519
|
+
* reported at most once a minute.
|
|
1520
|
+
*
|
|
1521
|
+
* Whether this instance hears the other instances is a state, `isSubscribed()`, that follows the
|
|
1522
|
+
* subscriber connection for the life of the process. `subscribe()` fails when the server answers
|
|
1523
|
+
* with an error reply (a wrong password, a missing permission), which no retry can fix; when the
|
|
1524
|
+
* server cannot be reached it resolves at once and the instance stays unsubscribed until a
|
|
1525
|
+
* connection succeeds. Each change of that state is logged once, not once per retry.
|
|
1385
1526
|
*
|
|
1386
1527
|
* @example
|
|
1387
1528
|
* ```ts
|
|
@@ -1397,14 +1538,24 @@ declare class RedisRealtimePubSub implements IRealtimePubSub {
|
|
|
1397
1538
|
#private;
|
|
1398
1539
|
private readonly channel;
|
|
1399
1540
|
private readonly handlers;
|
|
1541
|
+
private readonly logger;
|
|
1542
|
+
/** Payloads dropped as unparsable since the last report, and when that report was made. */
|
|
1543
|
+
private malformedDropped;
|
|
1544
|
+
private malformedReportedAt;
|
|
1400
1545
|
constructor(options: RedisRealtimePubSubOptions);
|
|
1546
|
+
/**
|
|
1547
|
+
* Whether this instance holds a confirmed subscription to the channel, so the events and
|
|
1548
|
+
* revocations other instances publish reach it. False before the first successful subscribe,
|
|
1549
|
+
* while the subscriber connection is down, and after the last handler has unsubscribed.
|
|
1550
|
+
*/
|
|
1551
|
+
isSubscribed(): boolean;
|
|
1401
1552
|
/** JSON-encodes the message and PUBLISHes it to the configured channel. */
|
|
1402
1553
|
publish(message: RealtimePubSubMessage): Promise<void>;
|
|
1403
1554
|
/**
|
|
1404
1555
|
* Lazily creates the single shared subscribe client on first call; returns an async
|
|
1405
1556
|
* unsubscribe that quits the client when the last handler is removed. Concurrent
|
|
1406
1557
|
* subscribe calls are idempotent — only one client is ever created. Malformed
|
|
1407
|
-
* payloads are dropped
|
|
1558
|
+
* payloads are dropped, and reported at most once a minute with their count.
|
|
1408
1559
|
*
|
|
1409
1560
|
* If the subscriber client cannot be created (e.g. Redis temporarily unavailable),
|
|
1410
1561
|
* the handler registration is rolled back and the cached init promise is cleared so
|
|
@@ -1414,6 +1565,16 @@ declare class RedisRealtimePubSub implements IRealtimePubSub {
|
|
|
1414
1565
|
/** Lazily create the single shared subscribe client (idempotent under concurrent calls). */
|
|
1415
1566
|
private ensureSubscriber;
|
|
1416
1567
|
private createSubscriber;
|
|
1568
|
+
private confirm;
|
|
1569
|
+
/** A server that was reached and refused the SUBSCRIBE after boot: it stays unsubscribed. */
|
|
1570
|
+
private refused;
|
|
1571
|
+
private markUp;
|
|
1572
|
+
private markDown;
|
|
1573
|
+
/**
|
|
1574
|
+
* Count a payload dropped as unparsable and report the count at most once per minute, so a
|
|
1575
|
+
* producer on an incompatible version is visible without flooding the log.
|
|
1576
|
+
*/
|
|
1577
|
+
private reportMalformed;
|
|
1417
1578
|
private dispatch;
|
|
1418
1579
|
}
|
|
1419
1580
|
|
|
@@ -1576,6 +1737,42 @@ declare function composeRoomId(prefix: keyof typeof ROOM_PREFIXES, ...parts: str
|
|
|
1576
1737
|
/** Describe a thrown or rejected value without throwing: `.message` on `null`, or `String()` on a prototype-less object, would. */
|
|
1577
1738
|
declare function describeError(reason: unknown): string;
|
|
1578
1739
|
|
|
1740
|
+
/**
|
|
1741
|
+
* @fileoverview The error a call rejects with when it could not reach what it was asked to act on.
|
|
1742
|
+
* @layer utils
|
|
1743
|
+
*/
|
|
1744
|
+
|
|
1745
|
+
/**
|
|
1746
|
+
* Builds the rejection for a call whose effect did not happen, such as a revocation that never
|
|
1747
|
+
* reached its connection. The stable code leads the message, as it does in the other errors this
|
|
1748
|
+
* library raises, and the original failure travels as `cause`.
|
|
1749
|
+
*
|
|
1750
|
+
* @param code - The stable error code to carry.
|
|
1751
|
+
* @param who - The class that raises it, shown in brackets.
|
|
1752
|
+
* @param what - What could not be reached.
|
|
1753
|
+
* @param cause - The failure underneath, whatever was thrown.
|
|
1754
|
+
*/
|
|
1755
|
+
declare function unavailableError(code: RealtimeErrorCode, who: string, what: string, cause: unknown): Error;
|
|
1756
|
+
|
|
1757
|
+
/**
|
|
1758
|
+
* @fileoverview Makes a delivery path's failure visible without failing the call that used it.
|
|
1759
|
+
* @layer utils
|
|
1760
|
+
*/
|
|
1761
|
+
|
|
1762
|
+
/**
|
|
1763
|
+
* Logs a delivery failure with its stable code and the operation, and hands it to the
|
|
1764
|
+
* `onDeliveryFailure` hook. The hook runs on its own: whether it throws or rejects, the failure
|
|
1765
|
+
* is logged and the caller carries on.
|
|
1766
|
+
*
|
|
1767
|
+
* @param logger - The raising class's logger.
|
|
1768
|
+
* @param hooks - The consumer's lifecycle hooks, if any.
|
|
1769
|
+
* @param failure - What failed; `error` may be whatever was thrown.
|
|
1770
|
+
* @param what - A short description for the log line.
|
|
1771
|
+
*/
|
|
1772
|
+
declare function reportDeliveryFailure(logger: Logger, hooks: IConnectionLifecycleHooks | undefined, failure: Omit<DeliveryFailure, 'error'> & {
|
|
1773
|
+
readonly error: unknown;
|
|
1774
|
+
}, what: string): void;
|
|
1775
|
+
|
|
1579
1776
|
/**
|
|
1580
1777
|
* @fileoverview Parser turning a raw HTTP `Cookie` header into a plain object.
|
|
1581
1778
|
* @layer utils
|
|
@@ -1670,31 +1867,4 @@ declare const RESERVED_EVENT_NAMES: {
|
|
|
1670
1867
|
/** Union of reserved event name values. */
|
|
1671
1868
|
type ReservedEventName = (typeof RESERVED_EVENT_NAMES)[keyof typeof RESERVED_EVENT_NAMES];
|
|
1672
1869
|
|
|
1673
|
-
|
|
1674
|
-
* @fileoverview Canonical error codes emitted by the library (the §14 catalog).
|
|
1675
|
-
* @layer shared
|
|
1676
|
-
*/
|
|
1677
|
-
/**
|
|
1678
|
-
* Canonical error codes emitted by the library. Map 1-to-1 with
|
|
1679
|
-
* `docs/technical_specification.md` §14.
|
|
1680
|
-
*
|
|
1681
|
-
* `TOO_MANY_CONNECTIONS` signals FIFO eviction: when a user exceeds
|
|
1682
|
-
* `maxConnectionsPerUser`, the OLDEST connection is evicted (closed with this
|
|
1683
|
-
* code) and the new one is admitted — it is never an HTTP 429 rejection.
|
|
1684
|
-
*/
|
|
1685
|
-
declare const REALTIME_ERROR_CODES: {
|
|
1686
|
-
readonly INVALID_OPTIONS: "REALTIME_INVALID_OPTIONS";
|
|
1687
|
-
readonly NO_AUTHENTICATOR: "REALTIME_NO_AUTHENTICATOR";
|
|
1688
|
-
readonly AUTH_FAILED: "REALTIME_AUTH_FAILED";
|
|
1689
|
-
readonly REAUTHENTICATION_FAILED: "REALTIME_REAUTHENTICATION_FAILED";
|
|
1690
|
-
readonly TOO_MANY_CONNECTIONS: "REALTIME_TOO_MANY_CONNECTIONS";
|
|
1691
|
-
readonly INVALID_TICKET: "REALTIME_INVALID_TICKET";
|
|
1692
|
-
readonly PUBSUB_UNAVAILABLE: "REALTIME_PUBSUB_UNAVAILABLE";
|
|
1693
|
-
readonly REDIS_ADAPTER_FAILED: "REALTIME_REDIS_ADAPTER_FAILED";
|
|
1694
|
-
readonly PAYLOAD_TOO_LARGE: "REALTIME_PAYLOAD_TOO_LARGE";
|
|
1695
|
-
readonly REPLAY_BUFFER_MISS: "REALTIME_REPLAY_BUFFER_MISS";
|
|
1696
|
-
};
|
|
1697
|
-
/** Union of canonical error code values. */
|
|
1698
|
-
type RealtimeErrorCode = (typeof REALTIME_ERROR_CODES)[keyof typeof REALTIME_ERROR_CODES];
|
|
1699
|
-
|
|
1700
|
-
export { type AuthenticationResult, BymaxRealtimeModule, type BymaxRealtimeModuleAsyncOptions, type BymaxRealtimeModuleOptions, type BymaxRealtimeModuleOptionsFactory, type ConnectionAuthContext, type ConnectionEventMeta, ConnectionRegistry, type CorsConfig, EventIdGenerator, EventReplayBuffer, HeartbeatService, type IConnectionAuthenticator, type IConnectionLifecycleHooks, type IOfflineQueueStorage, type IPresenceStorage, type IRealtimePubSub, type ITransport, InMemoryPubSub, OfflineQueueDeliveryService, type OfflineQueuedEvent, type PublicConnectionMeta, REALTIME_AUTHENTICATOR_TOKEN, REALTIME_ERROR_CODES, REALTIME_HOOKS_TOKEN, REALTIME_INSTANCE_ID_TOKEN, REALTIME_OFFLINE_QUEUE_TOKEN, REALTIME_OPTIONS_TOKEN, REALTIME_PRESENCE_TOKEN, REALTIME_PUBSUB_TOKEN, REALTIME_TRANSPORT_TOKEN, RESERVED_EVENT_NAMES, ROOM_PREFIXES, type RealtimeErrorCode, type RealtimeEvent, type RealtimePubSubMessage, RealtimePubSubSubscriber, RealtimeService, type ReauthenticationPolicy, ReauthenticationService, RedisOfflineQueue, type RedisOfflineQueueOptions, RedisRealtimePubSub, type RedisRealtimePubSubOptions, type ReservedEventName, type RoomPrefix, RoomRegistry, type SseOptions, type SseRealtimeModuleAsyncOptions, type SseRealtimeModuleOptions, SseSubscriptionHandler, SseTransport, type TransportMode, type TransportRegistration, type TransportWiring, type WebSocketOptions, type WebSocketRealtimeModuleAsyncOptions, type WebSocketRealtimeModuleOptions, assertIdentityIsNotBlank, composeForRoot, composeForRootAsync, composeRoomId, createSseController, describeError, parseCookieHeader, resolveAuthTenant, sseWiring };
|
|
1870
|
+
export { type AuthenticationResult, BymaxRealtimeModule, type BymaxRealtimeModuleAsyncOptions, type BymaxRealtimeModuleOptions, type BymaxRealtimeModuleOptionsFactory, type ConnectionAuthContext, type ConnectionEventMeta, ConnectionRegistry, type CorsConfig, type DeliveryFailure, EventIdGenerator, EventReplayBuffer, HeartbeatService, type IConnectionAuthenticator, type IConnectionLifecycleHooks, type IOfflineQueueStorage, type IPresenceStorage, type IRealtimePubSub, type ITransport, InMemoryPubSub, OfflineQueueDeliveryService, type OfflineQueuedEvent, type PublicConnectionMeta, REALTIME_AUTHENTICATOR_TOKEN, REALTIME_ERROR_CODES, REALTIME_HOOKS_TOKEN, REALTIME_INSTANCE_ID_TOKEN, REALTIME_OFFLINE_QUEUE_TOKEN, REALTIME_OPTIONS_TOKEN, REALTIME_PRESENCE_TOKEN, REALTIME_PUBSUB_TOKEN, REALTIME_TRANSPORT_TOKEN, RESERVED_EVENT_NAMES, ROOM_PREFIXES, type RealtimeErrorCode, type RealtimeEvent, type RealtimePubSubMessage, RealtimePubSubSubscriber, RealtimeService, type ReauthenticationPolicy, ReauthenticationService, RedisOfflineQueue, type RedisOfflineQueueOptions, RedisRealtimePubSub, type RedisRealtimePubSubOptions, type ReservedEventName, type RoomPrefix, RoomRegistry, type SseOptions, type SseRealtimeModuleAsyncOptions, type SseRealtimeModuleOptions, SseSubscriptionHandler, SseTransport, type TransportMode, type TransportRegistration, type TransportWiring, type WebSocketOptions, type WebSocketRealtimeModuleAsyncOptions, type WebSocketRealtimeModuleOptions, assertIdentityIsNotBlank, composeForRoot, composeForRootAsync, composeRoomId, createSseController, describeError, parseCookieHeader, reportDeliveryFailure, resolveAuthTenant, sseWiring, unavailableError };
|