@bymax-one/nest-realtime 1.2.15 → 1.2.17
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 +50 -3
- package/README.md +76 -24
- package/dist/internal/index.cjs +222 -105
- package/dist/internal/index.d.cts +72 -14
- package/dist/internal/index.d.ts +72 -14
- package/dist/internal/index.mjs +221 -106
- package/dist/react/index.cjs +163 -101
- package/dist/react/index.mjs +164 -102
- package/dist/websocket/index.cjs +18 -3
- package/dist/websocket/index.d.cts +4 -0
- package/dist/websocket/index.d.ts +4 -0
- package/dist/websocket/index.mjs +19 -4
- package/package.json +6 -3
|
@@ -105,8 +105,9 @@ interface AuthenticationResult {
|
|
|
105
105
|
* They are joined before the connection is announced or `onConnect` runs, so no event
|
|
106
106
|
* published to one of them can fall between admission and a later `joinRoom` — the
|
|
107
107
|
* window a join from `onConnect` leaves open. On SSE `onConnect` is not awaited
|
|
108
|
-
* and a hook that throws is only logged
|
|
109
|
-
* live, and stay, without its room; scope in `rooms`,
|
|
108
|
+
* and a hook that throws is only logged (unless `onConnectFailure` is `'close'`), so a
|
|
109
|
+
* connection scoped from there can go live, and stay, without its room; scope in `rooms`,
|
|
110
|
+
* not in `onConnect`.
|
|
110
111
|
*
|
|
111
112
|
* Each name must be a non-blank string of at most `ADMISSION_ROOM_LIMITS.MAX_ROOM_NAME_LENGTH`
|
|
112
113
|
* characters, must not start with `user:`, `tenant:` or `connection:` (the library
|
|
@@ -114,7 +115,7 @@ interface AuthenticationResult {
|
|
|
114
115
|
* hold at most `ADMISSION_ROOM_LIMITS.MAX_ROOMS` entries; duplicates join once.
|
|
115
116
|
* A result that breaks a rule is a contract violation, refused like a blank `userId`:
|
|
116
117
|
* a server fault, not a 401. The limits are bounds against abuse, not measurements.
|
|
117
|
-
* They apply to this field only; `joinRoom`
|
|
118
|
+
* They apply to this field only; `joinRoom` has no limit on count or length and refuses only the reserved prefixes.
|
|
118
119
|
*
|
|
119
120
|
* The rooms are fixed at admission. `revalidate` is handed them back, but a different
|
|
120
121
|
* set returned later is not re-synchronized; use `joinRoom` and `leaveRoom` for
|
|
@@ -488,6 +489,16 @@ interface BymaxRealtimeModuleOptions {
|
|
|
488
489
|
tenantResolver?: (auth: AuthenticationResult) => string | undefined | null;
|
|
489
490
|
hooks?: IConnectionLifecycleHooks;
|
|
490
491
|
hookTimeoutMs?: number;
|
|
492
|
+
/**
|
|
493
|
+
* What a failing `onConnect` does to the connection it was called for.
|
|
494
|
+
*
|
|
495
|
+
* `'ignore'` (the default): the failure is logged and the connection stays.
|
|
496
|
+
* `'close'`: the failure is logged and the connection is closed, on both transports. On
|
|
497
|
+
* WebSocket the connection is refused before it is announced; on SSE the hook is not awaited,
|
|
498
|
+
* so events published in the meantime may already have been delivered. Scope a connection in
|
|
499
|
+
* `AuthenticationResult.rooms`, not in the hook, when none may be missed.
|
|
500
|
+
*/
|
|
501
|
+
onConnectFailure?: 'ignore' | 'close';
|
|
491
502
|
authenticateTimeoutMs?: number;
|
|
492
503
|
maxPendingHandshakes?: number;
|
|
493
504
|
/**
|
|
@@ -939,6 +950,9 @@ declare class RealtimeService {
|
|
|
939
950
|
/**
|
|
940
951
|
* Send to a logical room. Use the prefix convention (`user:{id}`,
|
|
941
952
|
* `tenant:{id}`, `resource:{type}:{id}`) or a custom non-colliding id.
|
|
953
|
+
*
|
|
954
|
+
* @throws {Error} `REALTIME_AUTH_FAILED` when `roomId` is not a non-empty string: socket.io
|
|
955
|
+
* reads an array as several rooms.
|
|
942
956
|
*/
|
|
943
957
|
emitToRoom(roomId: string, event: string, data: unknown): Promise<void>;
|
|
944
958
|
/** Send to every connected client. Use sparingly. */
|
|
@@ -946,16 +960,19 @@ declare class RealtimeService {
|
|
|
946
960
|
/**
|
|
947
961
|
* Add a specific connection to a room.
|
|
948
962
|
*
|
|
949
|
-
*
|
|
950
|
-
*
|
|
951
|
-
*
|
|
963
|
+
* Rooms of the application's own are free-form, but a name that starts with `user:`,
|
|
964
|
+
* `tenant:` or `connection:` is refused, the rule that `AuthenticationResult.rooms` is
|
|
965
|
+
* held to: joining `tenant:<other>` would receive that tenant's events. A `roomId` that is
|
|
966
|
+
* not a non-empty string is refused too, whatever it holds: socket.io reads an array as
|
|
967
|
+
* several room names.
|
|
952
968
|
*
|
|
953
969
|
* Acts on a connection this instance holds; for any other id it resolves and changes
|
|
954
970
|
* nothing. A failure of the transport that holds the connection rejects the call.
|
|
955
971
|
*/
|
|
956
972
|
joinRoom(connectionId: string, roomId: string): Promise<void>;
|
|
957
973
|
/**
|
|
958
|
-
* Remove a specific connection from a room.
|
|
974
|
+
* Remove a specific connection from a room. A name that starts with `user:`, `tenant:` or
|
|
975
|
+
* `connection:` is refused, as in `joinRoom`, and so is a `roomId` that is not a non-empty string.
|
|
959
976
|
*
|
|
960
977
|
* Acts on a connection this instance holds; for any other id it resolves and changes
|
|
961
978
|
* nothing. A failure of the transport that holds the connection rejects the call.
|
|
@@ -1058,6 +1075,7 @@ declare class ReauthenticationService implements OnModuleInit, OnApplicationShut
|
|
|
1058
1075
|
private notify;
|
|
1059
1076
|
}
|
|
1060
1077
|
|
|
1078
|
+
/** How long a window of refusals is summarised in one log line. */
|
|
1061
1079
|
/**
|
|
1062
1080
|
* A handshake was refused because the authenticator could not be asked or did not answer in time:
|
|
1063
1081
|
* a fault of the system, not of the credentials, and carrying nothing about either.
|
|
@@ -1081,8 +1099,7 @@ declare class AuthenticationGate {
|
|
|
1081
1099
|
private readonly maxPending;
|
|
1082
1100
|
private readonly timeoutMs;
|
|
1083
1101
|
private pending;
|
|
1084
|
-
private
|
|
1085
|
-
private refused;
|
|
1102
|
+
private readonly refusals;
|
|
1086
1103
|
constructor(options: BymaxRealtimeModuleOptions, authenticator: IConnectionAuthenticator);
|
|
1087
1104
|
/**
|
|
1088
1105
|
* Ask the authenticator about one handshake.
|
|
@@ -1095,6 +1112,7 @@ declare class AuthenticationGate {
|
|
|
1095
1112
|
private refuse;
|
|
1096
1113
|
}
|
|
1097
1114
|
|
|
1115
|
+
/** How long a window of refusals is summarised in one log line. */
|
|
1098
1116
|
/** A handshake was refused because the instance already holds `maxConnections` connections. */
|
|
1099
1117
|
declare class ConnectionLimitError extends Error {
|
|
1100
1118
|
readonly limit: number;
|
|
@@ -1134,8 +1152,7 @@ declare class ConnectionAdmission {
|
|
|
1134
1152
|
private readonly holdMs;
|
|
1135
1153
|
/** The places held, oldest first, each with the time it is given back at whatever happens. */
|
|
1136
1154
|
private readonly held;
|
|
1137
|
-
private
|
|
1138
|
-
private refused;
|
|
1155
|
+
private readonly refusals;
|
|
1139
1156
|
constructor(options: BymaxRealtimeModuleOptions, registry: ConnectionRegistry);
|
|
1140
1157
|
/**
|
|
1141
1158
|
* Take a place for one connection.
|
|
@@ -1175,6 +1192,7 @@ declare class RoomRegistry {
|
|
|
1175
1192
|
countRooms(): number;
|
|
1176
1193
|
}
|
|
1177
1194
|
|
|
1195
|
+
/** How long a window of timeouts is summarised in one log line. */
|
|
1178
1196
|
/** What the first read of a reconnect's gap came to. */
|
|
1179
1197
|
interface OfflineQueueRead {
|
|
1180
1198
|
/** The gap events, in queue order. */
|
|
@@ -1204,8 +1222,7 @@ declare class OfflineQueueDeliveryService {
|
|
|
1204
1222
|
private readonly timeoutMs;
|
|
1205
1223
|
private readonly maxPending;
|
|
1206
1224
|
private pending;
|
|
1207
|
-
private
|
|
1208
|
-
private timedOut;
|
|
1225
|
+
private readonly timeouts;
|
|
1209
1226
|
constructor(storage?: IOfflineQueueStorage | undefined, hooks?: IConnectionLifecycleHooks | undefined, options?: BymaxRealtimeModuleOptions);
|
|
1210
1227
|
/**
|
|
1211
1228
|
* Return events for `userId` that arrived after `lastEventId` and are NOT
|
|
@@ -1805,6 +1822,7 @@ declare class SseSubscriptionHandler {
|
|
|
1805
1822
|
* so it never disrupts the connection lifecycle or live event delivery.
|
|
1806
1823
|
*
|
|
1807
1824
|
* @param invoke - A zero-arg function that calls the hook (handles optionality).
|
|
1825
|
+
* @param onFailure - What to do, once the failure is logged, when the hook failed.
|
|
1808
1826
|
*/
|
|
1809
1827
|
private fireHook;
|
|
1810
1828
|
}
|
|
@@ -1870,7 +1888,15 @@ declare class RealtimePubSubSubscriber implements OnModuleInit, OnApplicationShu
|
|
|
1870
1888
|
constructor(pubsub: IRealtimePubSub, instanceId: string, sse: SseTransport);
|
|
1871
1889
|
onModuleInit(): Promise<void>;
|
|
1872
1890
|
onApplicationShutdown(): Promise<void>;
|
|
1891
|
+
/**
|
|
1892
|
+
* Messages the subscriber cannot act on, counted and reported once for each window. The line
|
|
1893
|
+
* carries the count and the reason in a fixed vocabulary: an unknown op, or the class of the last
|
|
1894
|
+
* failure. The op and the failure's message can echo what whoever publishes to the channel
|
|
1895
|
+
* wrote, so neither is ever written.
|
|
1896
|
+
*/
|
|
1897
|
+
private readonly dropped;
|
|
1873
1898
|
private handle;
|
|
1899
|
+
private drop;
|
|
1874
1900
|
}
|
|
1875
1901
|
|
|
1876
1902
|
/** Options for RedisRealtimePubSub. */
|
|
@@ -1927,6 +1953,14 @@ declare class RedisRealtimePubSub implements IRealtimePubSub {
|
|
|
1927
1953
|
* returns, and never gives up on one waiting behind a peer that does not answer, so a revocation
|
|
1928
1954
|
* would wait out the whole outage and then be sent after its caller was told it failed. It is
|
|
1929
1955
|
* refused at once instead, and never handed to the client.
|
|
1956
|
+
*
|
|
1957
|
+
* A client that can publish but whose server stops answering is given {@link PUBLISH_WAIT_MS}:
|
|
1958
|
+
* after it the publish rejects the same way. That rejection means the server did not confirm the
|
|
1959
|
+
* publish in time, not that it was not delivered: the command was already written to the socket
|
|
1960
|
+
* and Redis can still process it when it answers, so a message can arrive after its caller was
|
|
1961
|
+
* told it failed. The command also stays queued in the client until the server answers or the
|
|
1962
|
+
* connection drops; `commandTimeout` on the host's ioredis client is what rejects the command
|
|
1963
|
+
* itself.
|
|
1930
1964
|
*/
|
|
1931
1965
|
publish(message: RealtimePubSubMessage): Promise<void>;
|
|
1932
1966
|
/**
|
|
@@ -2234,6 +2268,30 @@ type UnavailableError = ServiceUnavailableException & {
|
|
|
2234
2268
|
*/
|
|
2235
2269
|
declare function unavailableError(code: RealtimeErrorCode, who: string, what: string, cause: unknown): UnavailableError;
|
|
2236
2270
|
|
|
2271
|
+
/**
|
|
2272
|
+
* Refuse a room name that is not a non-empty string.
|
|
2273
|
+
*
|
|
2274
|
+
* socket.io's room calls take an array of names, so a value that is not a string would
|
|
2275
|
+
* skip every check written for strings and still reach the rooms. The public type is `string`;
|
|
2276
|
+
* the shape is refused rather than each element checked.
|
|
2277
|
+
*
|
|
2278
|
+
* @param operation - The public call that was made.
|
|
2279
|
+
* @param roomId - The room name it was given.
|
|
2280
|
+
* @throws Error carrying `REALTIME_AUTH_FAILED` when `roomId` is not a non-empty string.
|
|
2281
|
+
*/
|
|
2282
|
+
declare function requireRoomName(operation: string, roomId: unknown): asserts roomId is string;
|
|
2283
|
+
/**
|
|
2284
|
+
* Refuse a room name the library composes, for a call that would put a connection in it or take
|
|
2285
|
+
* it out. The message names the operation, the field and the prefix, never the room id, which is
|
|
2286
|
+
* the caller's input.
|
|
2287
|
+
*
|
|
2288
|
+
* @param operation - The public call that was made.
|
|
2289
|
+
* @param roomId - The room name it was given.
|
|
2290
|
+
* @throws Error carrying `REALTIME_AUTH_FAILED` when `roomId` is not a non-empty string, or starts
|
|
2291
|
+
* with a reserved prefix.
|
|
2292
|
+
*/
|
|
2293
|
+
declare function refuseReservedRoom(operation: string, roomId: unknown): void;
|
|
2294
|
+
|
|
2237
2295
|
/**
|
|
2238
2296
|
* @fileoverview The error every coded failure of this library is built with.
|
|
2239
2297
|
* @layer utils
|
|
@@ -2393,5 +2451,5 @@ declare const RESERVED_EVENT_NAMES: {
|
|
|
2393
2451
|
/** Union of reserved event name values. */
|
|
2394
2452
|
type ReservedEventName = (typeof RESERVED_EVENT_NAMES)[keyof typeof RESERVED_EVENT_NAMES];
|
|
2395
2453
|
|
|
2396
|
-
export { ADMISSION_ROOM_LIMITS, AuthenticationGate, AuthenticationUnavailableError, BymaxRealtimeModule, ConnectionAdmission, ConnectionLimitError, ConnectionRegistry, DEFAULT_HOOK_TIMEOUT_MS, EventIdGenerator, EventReplayBuffer, HeartbeatService, InMemoryPubSub, OfflineQueueDeliveryService, 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, RealtimePubSubSubscriber, RealtimeService, ReauthenticationService, RedisOfflineQueue, RedisRealtimePubSub, RoomRegistry, SseSubscriptionHandler, SseTransport, UNBOUNDED_TICKET, admitRooms, assertIdentityIsNotBlank, composeForRoot, composeForRootAsync, composeRoomId, createSseController, describeError, parseCookieHeader, quitWithin, realtimeError, reportDeliveryFailure, resolveAuthTenant, runHook, sseWiring, unavailableError };
|
|
2454
|
+
export { ADMISSION_ROOM_LIMITS, AuthenticationGate, AuthenticationUnavailableError, BymaxRealtimeModule, ConnectionAdmission, ConnectionLimitError, ConnectionRegistry, DEFAULT_HOOK_TIMEOUT_MS, EventIdGenerator, EventReplayBuffer, HeartbeatService, InMemoryPubSub, OfflineQueueDeliveryService, 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, RealtimePubSubSubscriber, RealtimeService, ReauthenticationService, RedisOfflineQueue, RedisRealtimePubSub, RoomRegistry, SseSubscriptionHandler, SseTransport, UNBOUNDED_TICKET, admitRooms, assertIdentityIsNotBlank, composeForRoot, composeForRootAsync, composeRoomId, createSseController, describeError, parseCookieHeader, quitWithin, realtimeError, refuseReservedRoom, reportDeliveryFailure, requireRoomName, resolveAuthTenant, runHook, sseWiring, unavailableError };
|
|
2397
2455
|
export type { AdmissionTicket, AuthenticationResult, AuthenticatorCallOptions, BymaxRealtimeModuleAsyncOptions, BymaxRealtimeModuleOptions, BymaxRealtimeModuleOptionsFactory, CodedError, ConnectionAuthContext, ConnectionEventMeta, CorsConfig, DeliveryFailure, IConnectionAuthenticator, IConnectionLifecycleHooks, IOfflineQueueStorage, IPresenceStorage, IRealtimePubSub, ITransport, OfflineQueuedEvent, PublicConnectionMeta, QuitableClient, RealtimeErrorCode, RealtimeEvent, RealtimePubSubMessage, ReauthenticationPolicy, RedisOfflineQueueOptions, RedisRealtimePubSubOptions, ReservedEventName, RoomPrefix, SseOptions, SseRealtimeModuleAsyncOptions, SseRealtimeModuleOptions, TransportMode, TransportRegistration, TransportWiring, WebSocketOptions, WebSocketRealtimeModuleAsyncOptions, WebSocketRealtimeModuleOptions };
|
package/dist/internal/index.d.ts
CHANGED
|
@@ -105,8 +105,9 @@ interface AuthenticationResult {
|
|
|
105
105
|
* They are joined before the connection is announced or `onConnect` runs, so no event
|
|
106
106
|
* published to one of them can fall between admission and a later `joinRoom` — the
|
|
107
107
|
* window a join from `onConnect` leaves open. On SSE `onConnect` is not awaited
|
|
108
|
-
* and a hook that throws is only logged
|
|
109
|
-
* live, and stay, without its room; scope in `rooms`,
|
|
108
|
+
* and a hook that throws is only logged (unless `onConnectFailure` is `'close'`), so a
|
|
109
|
+
* connection scoped from there can go live, and stay, without its room; scope in `rooms`,
|
|
110
|
+
* not in `onConnect`.
|
|
110
111
|
*
|
|
111
112
|
* Each name must be a non-blank string of at most `ADMISSION_ROOM_LIMITS.MAX_ROOM_NAME_LENGTH`
|
|
112
113
|
* characters, must not start with `user:`, `tenant:` or `connection:` (the library
|
|
@@ -114,7 +115,7 @@ interface AuthenticationResult {
|
|
|
114
115
|
* hold at most `ADMISSION_ROOM_LIMITS.MAX_ROOMS` entries; duplicates join once.
|
|
115
116
|
* A result that breaks a rule is a contract violation, refused like a blank `userId`:
|
|
116
117
|
* a server fault, not a 401. The limits are bounds against abuse, not measurements.
|
|
117
|
-
* They apply to this field only; `joinRoom`
|
|
118
|
+
* They apply to this field only; `joinRoom` has no limit on count or length and refuses only the reserved prefixes.
|
|
118
119
|
*
|
|
119
120
|
* The rooms are fixed at admission. `revalidate` is handed them back, but a different
|
|
120
121
|
* set returned later is not re-synchronized; use `joinRoom` and `leaveRoom` for
|
|
@@ -488,6 +489,16 @@ interface BymaxRealtimeModuleOptions {
|
|
|
488
489
|
tenantResolver?: (auth: AuthenticationResult) => string | undefined | null;
|
|
489
490
|
hooks?: IConnectionLifecycleHooks;
|
|
490
491
|
hookTimeoutMs?: number;
|
|
492
|
+
/**
|
|
493
|
+
* What a failing `onConnect` does to the connection it was called for.
|
|
494
|
+
*
|
|
495
|
+
* `'ignore'` (the default): the failure is logged and the connection stays.
|
|
496
|
+
* `'close'`: the failure is logged and the connection is closed, on both transports. On
|
|
497
|
+
* WebSocket the connection is refused before it is announced; on SSE the hook is not awaited,
|
|
498
|
+
* so events published in the meantime may already have been delivered. Scope a connection in
|
|
499
|
+
* `AuthenticationResult.rooms`, not in the hook, when none may be missed.
|
|
500
|
+
*/
|
|
501
|
+
onConnectFailure?: 'ignore' | 'close';
|
|
491
502
|
authenticateTimeoutMs?: number;
|
|
492
503
|
maxPendingHandshakes?: number;
|
|
493
504
|
/**
|
|
@@ -939,6 +950,9 @@ declare class RealtimeService {
|
|
|
939
950
|
/**
|
|
940
951
|
* Send to a logical room. Use the prefix convention (`user:{id}`,
|
|
941
952
|
* `tenant:{id}`, `resource:{type}:{id}`) or a custom non-colliding id.
|
|
953
|
+
*
|
|
954
|
+
* @throws {Error} `REALTIME_AUTH_FAILED` when `roomId` is not a non-empty string: socket.io
|
|
955
|
+
* reads an array as several rooms.
|
|
942
956
|
*/
|
|
943
957
|
emitToRoom(roomId: string, event: string, data: unknown): Promise<void>;
|
|
944
958
|
/** Send to every connected client. Use sparingly. */
|
|
@@ -946,16 +960,19 @@ declare class RealtimeService {
|
|
|
946
960
|
/**
|
|
947
961
|
* Add a specific connection to a room.
|
|
948
962
|
*
|
|
949
|
-
*
|
|
950
|
-
*
|
|
951
|
-
*
|
|
963
|
+
* Rooms of the application's own are free-form, but a name that starts with `user:`,
|
|
964
|
+
* `tenant:` or `connection:` is refused, the rule that `AuthenticationResult.rooms` is
|
|
965
|
+
* held to: joining `tenant:<other>` would receive that tenant's events. A `roomId` that is
|
|
966
|
+
* not a non-empty string is refused too, whatever it holds: socket.io reads an array as
|
|
967
|
+
* several room names.
|
|
952
968
|
*
|
|
953
969
|
* Acts on a connection this instance holds; for any other id it resolves and changes
|
|
954
970
|
* nothing. A failure of the transport that holds the connection rejects the call.
|
|
955
971
|
*/
|
|
956
972
|
joinRoom(connectionId: string, roomId: string): Promise<void>;
|
|
957
973
|
/**
|
|
958
|
-
* Remove a specific connection from a room.
|
|
974
|
+
* Remove a specific connection from a room. A name that starts with `user:`, `tenant:` or
|
|
975
|
+
* `connection:` is refused, as in `joinRoom`, and so is a `roomId` that is not a non-empty string.
|
|
959
976
|
*
|
|
960
977
|
* Acts on a connection this instance holds; for any other id it resolves and changes
|
|
961
978
|
* nothing. A failure of the transport that holds the connection rejects the call.
|
|
@@ -1058,6 +1075,7 @@ declare class ReauthenticationService implements OnModuleInit, OnApplicationShut
|
|
|
1058
1075
|
private notify;
|
|
1059
1076
|
}
|
|
1060
1077
|
|
|
1078
|
+
/** How long a window of refusals is summarised in one log line. */
|
|
1061
1079
|
/**
|
|
1062
1080
|
* A handshake was refused because the authenticator could not be asked or did not answer in time:
|
|
1063
1081
|
* a fault of the system, not of the credentials, and carrying nothing about either.
|
|
@@ -1081,8 +1099,7 @@ declare class AuthenticationGate {
|
|
|
1081
1099
|
private readonly maxPending;
|
|
1082
1100
|
private readonly timeoutMs;
|
|
1083
1101
|
private pending;
|
|
1084
|
-
private
|
|
1085
|
-
private refused;
|
|
1102
|
+
private readonly refusals;
|
|
1086
1103
|
constructor(options: BymaxRealtimeModuleOptions, authenticator: IConnectionAuthenticator);
|
|
1087
1104
|
/**
|
|
1088
1105
|
* Ask the authenticator about one handshake.
|
|
@@ -1095,6 +1112,7 @@ declare class AuthenticationGate {
|
|
|
1095
1112
|
private refuse;
|
|
1096
1113
|
}
|
|
1097
1114
|
|
|
1115
|
+
/** How long a window of refusals is summarised in one log line. */
|
|
1098
1116
|
/** A handshake was refused because the instance already holds `maxConnections` connections. */
|
|
1099
1117
|
declare class ConnectionLimitError extends Error {
|
|
1100
1118
|
readonly limit: number;
|
|
@@ -1134,8 +1152,7 @@ declare class ConnectionAdmission {
|
|
|
1134
1152
|
private readonly holdMs;
|
|
1135
1153
|
/** The places held, oldest first, each with the time it is given back at whatever happens. */
|
|
1136
1154
|
private readonly held;
|
|
1137
|
-
private
|
|
1138
|
-
private refused;
|
|
1155
|
+
private readonly refusals;
|
|
1139
1156
|
constructor(options: BymaxRealtimeModuleOptions, registry: ConnectionRegistry);
|
|
1140
1157
|
/**
|
|
1141
1158
|
* Take a place for one connection.
|
|
@@ -1175,6 +1192,7 @@ declare class RoomRegistry {
|
|
|
1175
1192
|
countRooms(): number;
|
|
1176
1193
|
}
|
|
1177
1194
|
|
|
1195
|
+
/** How long a window of timeouts is summarised in one log line. */
|
|
1178
1196
|
/** What the first read of a reconnect's gap came to. */
|
|
1179
1197
|
interface OfflineQueueRead {
|
|
1180
1198
|
/** The gap events, in queue order. */
|
|
@@ -1204,8 +1222,7 @@ declare class OfflineQueueDeliveryService {
|
|
|
1204
1222
|
private readonly timeoutMs;
|
|
1205
1223
|
private readonly maxPending;
|
|
1206
1224
|
private pending;
|
|
1207
|
-
private
|
|
1208
|
-
private timedOut;
|
|
1225
|
+
private readonly timeouts;
|
|
1209
1226
|
constructor(storage?: IOfflineQueueStorage | undefined, hooks?: IConnectionLifecycleHooks | undefined, options?: BymaxRealtimeModuleOptions);
|
|
1210
1227
|
/**
|
|
1211
1228
|
* Return events for `userId` that arrived after `lastEventId` and are NOT
|
|
@@ -1805,6 +1822,7 @@ declare class SseSubscriptionHandler {
|
|
|
1805
1822
|
* so it never disrupts the connection lifecycle or live event delivery.
|
|
1806
1823
|
*
|
|
1807
1824
|
* @param invoke - A zero-arg function that calls the hook (handles optionality).
|
|
1825
|
+
* @param onFailure - What to do, once the failure is logged, when the hook failed.
|
|
1808
1826
|
*/
|
|
1809
1827
|
private fireHook;
|
|
1810
1828
|
}
|
|
@@ -1870,7 +1888,15 @@ declare class RealtimePubSubSubscriber implements OnModuleInit, OnApplicationShu
|
|
|
1870
1888
|
constructor(pubsub: IRealtimePubSub, instanceId: string, sse: SseTransport);
|
|
1871
1889
|
onModuleInit(): Promise<void>;
|
|
1872
1890
|
onApplicationShutdown(): Promise<void>;
|
|
1891
|
+
/**
|
|
1892
|
+
* Messages the subscriber cannot act on, counted and reported once for each window. The line
|
|
1893
|
+
* carries the count and the reason in a fixed vocabulary: an unknown op, or the class of the last
|
|
1894
|
+
* failure. The op and the failure's message can echo what whoever publishes to the channel
|
|
1895
|
+
* wrote, so neither is ever written.
|
|
1896
|
+
*/
|
|
1897
|
+
private readonly dropped;
|
|
1873
1898
|
private handle;
|
|
1899
|
+
private drop;
|
|
1874
1900
|
}
|
|
1875
1901
|
|
|
1876
1902
|
/** Options for RedisRealtimePubSub. */
|
|
@@ -1927,6 +1953,14 @@ declare class RedisRealtimePubSub implements IRealtimePubSub {
|
|
|
1927
1953
|
* returns, and never gives up on one waiting behind a peer that does not answer, so a revocation
|
|
1928
1954
|
* would wait out the whole outage and then be sent after its caller was told it failed. It is
|
|
1929
1955
|
* refused at once instead, and never handed to the client.
|
|
1956
|
+
*
|
|
1957
|
+
* A client that can publish but whose server stops answering is given {@link PUBLISH_WAIT_MS}:
|
|
1958
|
+
* after it the publish rejects the same way. That rejection means the server did not confirm the
|
|
1959
|
+
* publish in time, not that it was not delivered: the command was already written to the socket
|
|
1960
|
+
* and Redis can still process it when it answers, so a message can arrive after its caller was
|
|
1961
|
+
* told it failed. The command also stays queued in the client until the server answers or the
|
|
1962
|
+
* connection drops; `commandTimeout` on the host's ioredis client is what rejects the command
|
|
1963
|
+
* itself.
|
|
1930
1964
|
*/
|
|
1931
1965
|
publish(message: RealtimePubSubMessage): Promise<void>;
|
|
1932
1966
|
/**
|
|
@@ -2234,6 +2268,30 @@ type UnavailableError = ServiceUnavailableException & {
|
|
|
2234
2268
|
*/
|
|
2235
2269
|
declare function unavailableError(code: RealtimeErrorCode, who: string, what: string, cause: unknown): UnavailableError;
|
|
2236
2270
|
|
|
2271
|
+
/**
|
|
2272
|
+
* Refuse a room name that is not a non-empty string.
|
|
2273
|
+
*
|
|
2274
|
+
* socket.io's room calls take an array of names, so a value that is not a string would
|
|
2275
|
+
* skip every check written for strings and still reach the rooms. The public type is `string`;
|
|
2276
|
+
* the shape is refused rather than each element checked.
|
|
2277
|
+
*
|
|
2278
|
+
* @param operation - The public call that was made.
|
|
2279
|
+
* @param roomId - The room name it was given.
|
|
2280
|
+
* @throws Error carrying `REALTIME_AUTH_FAILED` when `roomId` is not a non-empty string.
|
|
2281
|
+
*/
|
|
2282
|
+
declare function requireRoomName(operation: string, roomId: unknown): asserts roomId is string;
|
|
2283
|
+
/**
|
|
2284
|
+
* Refuse a room name the library composes, for a call that would put a connection in it or take
|
|
2285
|
+
* it out. The message names the operation, the field and the prefix, never the room id, which is
|
|
2286
|
+
* the caller's input.
|
|
2287
|
+
*
|
|
2288
|
+
* @param operation - The public call that was made.
|
|
2289
|
+
* @param roomId - The room name it was given.
|
|
2290
|
+
* @throws Error carrying `REALTIME_AUTH_FAILED` when `roomId` is not a non-empty string, or starts
|
|
2291
|
+
* with a reserved prefix.
|
|
2292
|
+
*/
|
|
2293
|
+
declare function refuseReservedRoom(operation: string, roomId: unknown): void;
|
|
2294
|
+
|
|
2237
2295
|
/**
|
|
2238
2296
|
* @fileoverview The error every coded failure of this library is built with.
|
|
2239
2297
|
* @layer utils
|
|
@@ -2393,5 +2451,5 @@ declare const RESERVED_EVENT_NAMES: {
|
|
|
2393
2451
|
/** Union of reserved event name values. */
|
|
2394
2452
|
type ReservedEventName = (typeof RESERVED_EVENT_NAMES)[keyof typeof RESERVED_EVENT_NAMES];
|
|
2395
2453
|
|
|
2396
|
-
export { ADMISSION_ROOM_LIMITS, AuthenticationGate, AuthenticationUnavailableError, BymaxRealtimeModule, ConnectionAdmission, ConnectionLimitError, ConnectionRegistry, DEFAULT_HOOK_TIMEOUT_MS, EventIdGenerator, EventReplayBuffer, HeartbeatService, InMemoryPubSub, OfflineQueueDeliveryService, 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, RealtimePubSubSubscriber, RealtimeService, ReauthenticationService, RedisOfflineQueue, RedisRealtimePubSub, RoomRegistry, SseSubscriptionHandler, SseTransport, UNBOUNDED_TICKET, admitRooms, assertIdentityIsNotBlank, composeForRoot, composeForRootAsync, composeRoomId, createSseController, describeError, parseCookieHeader, quitWithin, realtimeError, reportDeliveryFailure, resolveAuthTenant, runHook, sseWiring, unavailableError };
|
|
2454
|
+
export { ADMISSION_ROOM_LIMITS, AuthenticationGate, AuthenticationUnavailableError, BymaxRealtimeModule, ConnectionAdmission, ConnectionLimitError, ConnectionRegistry, DEFAULT_HOOK_TIMEOUT_MS, EventIdGenerator, EventReplayBuffer, HeartbeatService, InMemoryPubSub, OfflineQueueDeliveryService, 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, RealtimePubSubSubscriber, RealtimeService, ReauthenticationService, RedisOfflineQueue, RedisRealtimePubSub, RoomRegistry, SseSubscriptionHandler, SseTransport, UNBOUNDED_TICKET, admitRooms, assertIdentityIsNotBlank, composeForRoot, composeForRootAsync, composeRoomId, createSseController, describeError, parseCookieHeader, quitWithin, realtimeError, refuseReservedRoom, reportDeliveryFailure, requireRoomName, resolveAuthTenant, runHook, sseWiring, unavailableError };
|
|
2397
2455
|
export type { AdmissionTicket, AuthenticationResult, AuthenticatorCallOptions, BymaxRealtimeModuleAsyncOptions, BymaxRealtimeModuleOptions, BymaxRealtimeModuleOptionsFactory, CodedError, ConnectionAuthContext, ConnectionEventMeta, CorsConfig, DeliveryFailure, IConnectionAuthenticator, IConnectionLifecycleHooks, IOfflineQueueStorage, IPresenceStorage, IRealtimePubSub, ITransport, OfflineQueuedEvent, PublicConnectionMeta, QuitableClient, RealtimeErrorCode, RealtimeEvent, RealtimePubSubMessage, ReauthenticationPolicy, RedisOfflineQueueOptions, RedisRealtimePubSubOptions, ReservedEventName, RoomPrefix, SseOptions, SseRealtimeModuleAsyncOptions, SseRealtimeModuleOptions, TransportMode, TransportRegistration, TransportWiring, WebSocketOptions, WebSocketRealtimeModuleAsyncOptions, WebSocketRealtimeModuleOptions };
|