@bymax-one/nest-realtime 1.2.13 → 1.2.15

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.
@@ -34,6 +34,7 @@ var REALTIME_ERROR_CODES = {
34
34
  AUTH_FAILED: "REALTIME_AUTH_FAILED",
35
35
  REAUTHENTICATION_FAILED: "REALTIME_REAUTHENTICATION_FAILED",
36
36
  TOO_MANY_CONNECTIONS: "REALTIME_TOO_MANY_CONNECTIONS",
37
+ SLOW_CONSUMER: "REALTIME_SLOW_CONSUMER",
37
38
  INVALID_TICKET: "REALTIME_INVALID_TICKET",
38
39
  PUBSUB_UNAVAILABLE: "REALTIME_PUBSUB_UNAVAILABLE",
39
40
  TRANSPORT_UNAVAILABLE: "REALTIME_TRANSPORT_UNAVAILABLE",
@@ -47,8 +48,13 @@ var DEFAULT_SSE = {
47
48
  endpoint: "/realtime/sse",
48
49
  heartbeatMs: 3e4,
49
50
  replayBufferSize: 100,
51
+ replayTtlMs: 3e5,
52
+ replayMaxIdleUsers: 1e3,
50
53
  maxConnectionsPerUser: 5,
51
- emitConnectionEvent: true
54
+ emitConnectionEvent: true,
55
+ maxQueuedBytes: 2 * 1024 * 1024,
56
+ maxQueuedEvents: 1e3,
57
+ stallHeartbeats: 3
52
58
  };
53
59
  function applyDefaults(options) {
54
60
  return Object.freeze({
@@ -67,6 +73,7 @@ var REALTIME_PRESENCE_TOKEN = /* @__PURE__ */ Symbol("BYMAX_REALTIME_PRESENCE");
67
73
  var REALTIME_HOOKS_TOKEN = /* @__PURE__ */ Symbol("BYMAX_REALTIME_HOOKS");
68
74
  var REALTIME_INSTANCE_ID_TOKEN = /* @__PURE__ */ Symbol("BYMAX_REALTIME_INSTANCE_ID");
69
75
  var DEFAULT_HEARTBEAT_MS = 3e4;
76
+ var DEFAULT_HOOK_TIMEOUT_MS = 5e3;
70
77
  var HEARTBEAT_MIN_MS = 5e3;
71
78
  var HEARTBEAT_MAX_MS = 9e4;
72
79
 
@@ -102,11 +109,48 @@ function validateOptions(options) {
102
109
  { who: "BymaxRealtimeModule" }
103
110
  );
104
111
  }
112
+ validateHookTimeout(options);
105
113
  validateSseOptions(options);
106
114
  validateReauthPolicy(options);
107
115
  }
116
+ var MAX_TIMER_MS = 2147483647;
117
+ function assertInteger(path, value, least, most) {
118
+ if (value === void 0) return;
119
+ const valid = typeof value === "number" && Number.isInteger(value) && value >= least && (most === void 0 || value <= most);
120
+ if (valid) return;
121
+ throw realtimeError(
122
+ REALTIME_ERROR_CODES.INVALID_OPTIONS,
123
+ `options.${path} must be an integer >= ${least}${most === void 0 ? "" : ` and <= ${most}`}, got ${String(value)}`,
124
+ { who: "BymaxRealtimeModule" }
125
+ );
126
+ }
127
+ function validateHookTimeout(options) {
128
+ assertInteger("hookTimeoutMs", options.hookTimeoutMs, 1, MAX_TIMER_MS);
129
+ assertInteger("authenticateTimeoutMs", options.authenticateTimeoutMs, 1, MAX_TIMER_MS);
130
+ assertInteger("maxPendingHandshakes", options.maxPendingHandshakes, 1);
131
+ assertInteger("maxConnections", options.maxConnections, 1);
132
+ assertInteger("websocket.pingIntervalMs", options.websocket?.pingIntervalMs, 1, MAX_TIMER_MS);
133
+ assertInteger("websocket.pingTimeoutMs", options.websocket?.pingTimeoutMs, 1, MAX_TIMER_MS);
134
+ }
135
+ var REAUTH_INTEGER_OPTIONS = [
136
+ ["intervalSeconds", 1, Math.floor(MAX_TIMER_MS / 1e3)],
137
+ ["cacheTtlMs", 0, void 0],
138
+ ["revalidateTimeoutMs", 1, MAX_TIMER_MS],
139
+ ["concurrency", 1, void 0]
140
+ ];
108
141
  function validateReauthPolicy(options) {
109
142
  const policy = options.reauthenticationPolicy;
143
+ for (const [name, least, most] of REAUTH_INTEGER_OPTIONS) {
144
+ assertInteger(`reauthenticationPolicy.${name}`, policy?.[name], least, most);
145
+ }
146
+ const onFailure = policy?.onFailure;
147
+ if (onFailure !== void 0 && onFailure !== "disconnect" && onFailure !== "event") {
148
+ throw realtimeError(
149
+ REALTIME_ERROR_CODES.INVALID_OPTIONS,
150
+ `options.reauthenticationPolicy.onFailure must be 'disconnect' or 'event', got ${String(onFailure)}`,
151
+ { who: "BymaxRealtimeModule" }
152
+ );
153
+ }
110
154
  if (policy?.cacheTtlMs !== void 0 && policy.intervalSeconds !== void 0 && policy.cacheTtlMs > policy.intervalSeconds * 1e3) {
111
155
  common.Logger.warn(
112
156
  `[BymaxRealtimeModule] reauthenticationPolicy.cacheTtlMs (${policy.cacheTtlMs} ms) exceeds intervalSeconds*1000 (${policy.intervalSeconds * 1e3} ms): the positive reauth cache outlives the interval, so revalidate is skipped on ticks within the cache window \u2014 reauthentication is effectively weakened`,
@@ -131,6 +175,18 @@ function validateSseOptions(options) {
131
175
  { who: "BymaxRealtimeModule" }
132
176
  );
133
177
  }
178
+ assertInteger("sse.replayTtlMs", sse?.replayTtlMs, 1, MAX_TIMER_MS);
179
+ assertInteger("sse.replayMaxIdleUsers", sse?.replayMaxIdleUsers, 1);
180
+ for (const name of ["maxQueuedBytes", "maxQueuedEvents", "stallHeartbeats"]) {
181
+ const value = sse?.[name];
182
+ if (value !== void 0 && !(typeof value === "number" && Number.isInteger(value) && value >= 0)) {
183
+ throw realtimeError(
184
+ REALTIME_ERROR_CODES.INVALID_OPTIONS,
185
+ `options.sse.${name} must be an integer >= 0 (0 switches the bound off), got ${String(value)}`,
186
+ { who: "BymaxRealtimeModule" }
187
+ );
188
+ }
189
+ }
134
190
  if (sse?.maxConnectionsPerUser !== void 0 && sse.maxConnectionsPerUser < 0) {
135
191
  throw realtimeError(
136
192
  REALTIME_ERROR_CODES.INVALID_OPTIONS,
@@ -164,20 +220,41 @@ function reportDeliveryFailure(logger, hooks, failure, what) {
164
220
 
165
221
  // src/server/offline-queue/offline-queue-delivery.service.ts
166
222
  var RETRIEVE_LIMIT = 200;
223
+ var DEFAULT_TIMEOUT_MS = 1e4;
224
+ var DEFAULT_MAX_PENDING = 1e3;
225
+ var REPORT_WINDOW_MS = 1e4;
226
+ var OfflineQueueTimeoutError = class extends Error {
227
+ constructor() {
228
+ super("the offline queue did not answer in time");
229
+ }
230
+ };
167
231
  exports.OfflineQueueDeliveryService = class OfflineQueueDeliveryService {
168
- constructor(storage, hooks) {
232
+ constructor(storage, hooks, options) {
169
233
  this.storage = storage;
170
234
  this.hooks = hooks;
235
+ this.timeoutMs = options?.authenticateTimeoutMs ?? DEFAULT_TIMEOUT_MS;
236
+ this.maxPending = options?.maxPendingHandshakes ?? DEFAULT_MAX_PENDING;
171
237
  }
172
238
  storage;
173
239
  hooks;
174
240
  logger = new common.Logger(exports.OfflineQueueDeliveryService.name);
241
+ timeoutMs;
242
+ maxPending;
243
+ pending = 0;
244
+ windowStartedAt = Number.NEGATIVE_INFINITY;
245
+ timedOut = 0;
175
246
  async retrieve(userId, lastEventId, ringBufferIds) {
176
- if (!this.storage) return [];
247
+ const { events } = await this.retrieveGap(userId, lastEventId);
248
+ return events.filter((e) => !ringBufferIds.has(e.id));
249
+ }
250
+ async retrieveGap(userId, lastEventId) {
251
+ const storage = this.storage;
252
+ if (!storage) return { events: [], degraded: false };
177
253
  let events;
178
254
  try {
179
- events = await this.storage.retrieveSince(userId, lastEventId, RETRIEVE_LIMIT);
255
+ events = await this.read(storage, userId, lastEventId, RETRIEVE_LIMIT);
180
256
  } catch (err) {
257
+ if (err instanceof OfflineQueueTimeoutError) throw err;
181
258
  reportDeliveryFailure(
182
259
  this.logger,
183
260
  this.hooks,
@@ -188,14 +265,14 @@ exports.OfflineQueueDeliveryService = class OfflineQueueDeliveryService {
188
265
  },
189
266
  "Offline queue retrieve failed"
190
267
  );
191
- return [];
268
+ return { events: [], degraded: true };
192
269
  }
193
270
  if (events.length === RETRIEVE_LIMIT) {
194
271
  this.logger.warn(
195
272
  `Offline queue retrieve hit the ${RETRIEVE_LIMIT}-event limit for user; older gap events may be dropped.`
196
273
  );
197
274
  }
198
- return events.filter((e) => !ringBufferIds.has(e.id));
275
+ return { events, degraded: false };
199
276
  }
200
277
  async acknowledge(userId, events) {
201
278
  if (!this.storage || events.length === 0) return;
@@ -206,13 +283,60 @@ exports.OfflineQueueDeliveryService = class OfflineQueueDeliveryService {
206
283
  this.logger.warn(`Offline queue acknowledge failed: ${describeError(err)}`);
207
284
  }
208
285
  }
286
+ async retrieveAppended(userId, lastEventId, read) {
287
+ const storage = this.storage;
288
+ const room = RETRIEVE_LIMIT - read.events.length;
289
+ if (!storage || read.degraded || room <= 0) return [];
290
+ return this.read(storage, userId, read.events.at(-1)?.id ?? lastEventId, room);
291
+ }
292
+ async read(storage, userId, sinceId, limit) {
293
+ if (this.pending >= this.maxPending) {
294
+ this.countTimeout();
295
+ throw new OfflineQueueTimeoutError();
296
+ }
297
+ try {
298
+ const call = Promise.resolve(storage.retrieveSince(userId, sinceId, limit));
299
+ this.pending += 1;
300
+ const settled = () => void (this.pending -= 1);
301
+ call.then(settled, settled);
302
+ return await this.withinDeadline(call);
303
+ } catch (err) {
304
+ if (err instanceof OfflineQueueTimeoutError) this.countTimeout();
305
+ throw err;
306
+ }
307
+ }
308
+ async withinDeadline(read) {
309
+ let timer;
310
+ const expired = new Promise((_resolve, reject) => {
311
+ timer = setTimeout(() => reject(new OfflineQueueTimeoutError()), this.timeoutMs);
312
+ timer.unref();
313
+ });
314
+ try {
315
+ return await Promise.race([read, expired]);
316
+ } finally {
317
+ clearTimeout(timer);
318
+ }
319
+ }
320
+ countTimeout() {
321
+ this.timedOut += 1;
322
+ const now = performance.now();
323
+ if (now - this.windowStartedAt < REPORT_WINDOW_MS) return;
324
+ this.windowStartedAt = now;
325
+ const count = this.timedOut;
326
+ this.timedOut = 0;
327
+ this.logger.warn(
328
+ `reconnects given up on since the last report: ${count}, because the offline queue did not answer in ${this.timeoutMs} ms or already had ${this.maxPending} reads waiting`
329
+ );
330
+ }
209
331
  };
210
332
  exports.OfflineQueueDeliveryService = __decorateClass([
211
333
  common.Injectable(),
212
334
  __decorateParam(0, common.Optional()),
213
335
  __decorateParam(0, common.Inject(REALTIME_OFFLINE_QUEUE_TOKEN)),
214
336
  __decorateParam(1, common.Optional()),
215
- __decorateParam(1, common.Inject(REALTIME_HOOKS_TOKEN))
337
+ __decorateParam(1, common.Inject(REALTIME_HOOKS_TOKEN)),
338
+ __decorateParam(2, common.Optional()),
339
+ __decorateParam(2, common.Inject(REALTIME_OPTIONS_TOKEN))
216
340
  ], exports.OfflineQueueDeliveryService);
217
341
 
218
342
  // src/shared/constants/reserved-events.constants.ts
@@ -238,7 +362,7 @@ var ROOM_PREFIXES = {
238
362
  RESOURCE: "resource"
239
363
  };
240
364
 
241
- // src/server/utils/assert-admission-rooms.ts
365
+ // src/server/utils/admit-rooms.ts
242
366
  var RESERVED_ROOM_PREFIXES = [
243
367
  `${ROOM_PREFIXES.USER}:`,
244
368
  `${ROOM_PREFIXES.TENANT}:`,
@@ -250,14 +374,20 @@ function refuse(detail) {
250
374
  `the authenticator returned rooms that are not valid: ${detail}. Fix the authenticator; the limits are bounds against abuse and apply to this field only.`
251
375
  );
252
376
  }
253
- function assertAdmissionRooms(auth) {
377
+ function admitRooms(auth) {
254
378
  const { rooms } = auth;
255
- if (rooms === void 0) return;
379
+ if (rooms === void 0) return auth;
256
380
  if (!Array.isArray(rooms)) refuse("`rooms` is not an array");
257
- if (rooms.length > ADMISSION_ROOM_LIMITS.MAX_ROOMS) {
258
- refuse(`${rooms.length} rooms exceeds the limit of ${ADMISSION_ROOM_LIMITS.MAX_ROOMS}`);
259
- }
381
+ const admitted = [];
260
382
  for (const room of rooms) {
383
+ if (admitted.length === ADMISSION_ROOM_LIMITS.MAX_ROOMS) {
384
+ refuse(
385
+ `more than ${ADMISSION_ROOM_LIMITS.MAX_ROOMS} rooms: the limit is ${ADMISSION_ROOM_LIMITS.MAX_ROOMS}`
386
+ );
387
+ }
388
+ admitted.push(room);
389
+ }
390
+ for (const room of admitted) {
261
391
  if (typeof room !== "string" || room.trim().length === 0) {
262
392
  refuse("every room must be a non-blank string");
263
393
  }
@@ -267,6 +397,7 @@ function assertAdmissionRooms(auth) {
267
397
  const reserved = RESERVED_ROOM_PREFIXES.find((prefix) => room.startsWith(prefix));
268
398
  if (reserved !== void 0) refuse(`a room name starts with the reserved prefix "${reserved}"`);
269
399
  }
400
+ return { ...auth, rooms: Object.freeze(admitted) };
270
401
  }
271
402
 
272
403
  // src/server/utils/assert-identity.ts
@@ -328,6 +459,73 @@ function resolveClientAddress(request) {
328
459
  }
329
460
  return peerAddress(request.socket?.remoteAddress);
330
461
  }
462
+ var REPORT_WINDOW_MS2 = 1e4;
463
+ var AuthenticationUnavailableError = class extends Error {
464
+ constructor(reason) {
465
+ super(
466
+ reason === "saturated" ? "too many handshakes are waiting for the authenticator" : "the authenticator did not answer in time"
467
+ );
468
+ this.reason = reason;
469
+ }
470
+ reason;
471
+ };
472
+ exports.AuthenticationGate = class AuthenticationGate {
473
+ constructor(options, authenticator) {
474
+ this.authenticator = authenticator;
475
+ this.maxPending = options.maxPendingHandshakes ?? 1e3;
476
+ this.timeoutMs = options.authenticateTimeoutMs ?? 1e4;
477
+ }
478
+ authenticator;
479
+ logger = new common.Logger(exports.AuthenticationGate.name);
480
+ maxPending;
481
+ timeoutMs;
482
+ pending = 0;
483
+ windowStartedAt = Number.NEGATIVE_INFINITY;
484
+ refused = { saturated: 0, timeout: 0 };
485
+ async authenticate(context) {
486
+ if (this.pending >= this.maxPending) {
487
+ this.refuse("saturated");
488
+ throw new AuthenticationUnavailableError("saturated");
489
+ }
490
+ this.pending += 1;
491
+ const controller = new AbortController();
492
+ const call = (async () => this.authenticator.authenticate(context, { signal: controller.signal }))();
493
+ const release = () => {
494
+ this.pending -= 1;
495
+ };
496
+ call.then(release, release);
497
+ let timer;
498
+ const timedOut = new Promise((_resolve, reject) => {
499
+ timer = setTimeout(() => {
500
+ this.refuse("timeout");
501
+ reject(new AuthenticationUnavailableError("timeout"));
502
+ controller.abort();
503
+ }, this.timeoutMs);
504
+ timer.unref();
505
+ });
506
+ try {
507
+ return await Promise.race([call, timedOut]);
508
+ } finally {
509
+ clearTimeout(timer);
510
+ }
511
+ }
512
+ refuse(reason) {
513
+ this.refused[reason] += 1;
514
+ const now = performance.now();
515
+ if (now - this.windowStartedAt < REPORT_WINDOW_MS2) return;
516
+ this.windowStartedAt = now;
517
+ const { saturated, timeout } = this.refused;
518
+ this.refused = { saturated: 0, timeout: 0 };
519
+ this.logger.warn(
520
+ `handshakes refused since the last report: ${saturated} because ${this.maxPending} were already waiting for the authenticator, ${timeout} because it did not answer in ${this.timeoutMs} ms`
521
+ );
522
+ }
523
+ };
524
+ exports.AuthenticationGate = __decorateClass([
525
+ common.Injectable(),
526
+ __decorateParam(0, common.Inject(REALTIME_OPTIONS_TOKEN)),
527
+ __decorateParam(1, common.Inject(REALTIME_AUTHENTICATOR_TOKEN))
528
+ ], exports.AuthenticationGate);
331
529
  exports.ConnectionRegistry = class ConnectionRegistry {
332
530
  byId = /* @__PURE__ */ new Map();
333
531
  byUserId = /* @__PURE__ */ new Map();
@@ -393,6 +591,109 @@ exports.ConnectionRegistry = class ConnectionRegistry {
393
591
  exports.ConnectionRegistry = __decorateClass([
394
592
  common.Injectable()
395
593
  ], exports.ConnectionRegistry);
594
+
595
+ // src/server/services/connection-admission.service.ts
596
+ var DEFAULT_AUTHENTICATE_TIMEOUT_MS = 1e4;
597
+ var DEFAULT_MAX_CONNECTIONS = 1e4;
598
+ var HOLD_MARGIN_MS = 5e3;
599
+ var REPORT_WINDOW_MS3 = 1e4;
600
+ var ConnectionLimitError = class extends Error {
601
+ constructor(limit) {
602
+ super(`the instance already holds ${limit} connections`);
603
+ this.limit = limit;
604
+ }
605
+ limit;
606
+ };
607
+ var UNBOUNDED_TICKET = {
608
+ release: () => void 0,
609
+ renew: () => void 0
610
+ };
611
+ exports.ConnectionAdmission = class ConnectionAdmission {
612
+ constructor(options, registry) {
613
+ this.registry = registry;
614
+ this.max = options.maxConnections ?? DEFAULT_MAX_CONNECTIONS;
615
+ this.holdMs = (options.authenticateTimeoutMs ?? DEFAULT_AUTHENTICATE_TIMEOUT_MS) + HOLD_MARGIN_MS;
616
+ }
617
+ registry;
618
+ logger = new common.Logger(exports.ConnectionAdmission.name);
619
+ max;
620
+ holdMs;
621
+ held = /* @__PURE__ */ new Map();
622
+ windowStartedAt = Number.NEGATIVE_INFINITY;
623
+ refused = 0;
624
+ admit() {
625
+ const place = /* @__PURE__ */ Symbol("place");
626
+ this.take(place);
627
+ let released = false;
628
+ return {
629
+ release: () => {
630
+ released = true;
631
+ this.held.delete(place);
632
+ },
633
+ renew: () => {
634
+ this.reclaim();
635
+ if (!released && !this.held.has(place)) this.take(place);
636
+ }
637
+ };
638
+ }
639
+ take(place) {
640
+ this.reclaim();
641
+ if (this.registry.count() + this.held.size >= this.max) {
642
+ this.refuse();
643
+ throw new ConnectionLimitError(this.max);
644
+ }
645
+ this.held.set(place, performance.now() + this.holdMs);
646
+ }
647
+ reclaim() {
648
+ const now = performance.now();
649
+ for (const [place, until] of this.held) {
650
+ if (until > now) break;
651
+ this.held.delete(place);
652
+ }
653
+ }
654
+ refuse() {
655
+ this.refused += 1;
656
+ const now = performance.now();
657
+ if (now - this.windowStartedAt < REPORT_WINDOW_MS3) return;
658
+ this.windowStartedAt = now;
659
+ const count = this.refused;
660
+ this.refused = 0;
661
+ this.logger.warn(
662
+ `connections refused since the last report: ${count}, because the instance already holds ${this.max} (maxConnections)`
663
+ );
664
+ }
665
+ };
666
+ exports.ConnectionAdmission = __decorateClass([
667
+ common.Injectable(),
668
+ __decorateParam(0, common.Inject(REALTIME_OPTIONS_TOKEN)),
669
+ __decorateParam(1, common.Inject(exports.ConnectionRegistry))
670
+ ], exports.ConnectionAdmission);
671
+
672
+ // src/server/utils/run-hook.ts
673
+ async function runHook(invoke, timeoutMs) {
674
+ const run = (async () => {
675
+ await invoke();
676
+ })();
677
+ let timer;
678
+ try {
679
+ if (timeoutMs === void 0) await run;
680
+ else {
681
+ const timedOut = new Promise((_resolve, reject) => {
682
+ timer = setTimeout(
683
+ () => reject(new Error(`did not settle within ${timeoutMs} ms`)),
684
+ timeoutMs
685
+ );
686
+ timer.unref();
687
+ });
688
+ await Promise.race([run, timedOut]);
689
+ }
690
+ clearTimeout(timer);
691
+ return void 0;
692
+ } catch (error) {
693
+ clearTimeout(timer);
694
+ return { error };
695
+ }
696
+ }
396
697
  var COUNTER_WIDTH = 6;
397
698
  exports.EventIdGenerator = class EventIdGenerator {
398
699
  lastMs = 0;
@@ -466,10 +767,9 @@ exports.RoomRegistry = __decorateClass([
466
767
  function composeRoomId(prefix, ...parts) {
467
768
  return [ROOM_PREFIXES[prefix], ...parts].join(":");
468
769
  }
469
-
470
- // src/server/utils/unavailable-error.ts
471
770
  function unavailableError(code, who, what, cause) {
472
- return realtimeError(code, `${what} (${describeError(cause)})`, { who, cause });
771
+ const { message } = realtimeError(code, `${what} (${describeError(cause)})`, { who });
772
+ return Object.assign(new common.ServiceUnavailableException(), { code, message, cause });
473
773
  }
474
774
  exports.InMemoryPubSub = class InMemoryPubSub {
475
775
  handlers = /* @__PURE__ */ new Set();
@@ -493,28 +793,69 @@ exports.InMemoryPubSub = __decorateClass([
493
793
  common.Injectable()
494
794
  ], exports.InMemoryPubSub);
495
795
  var DEFAULT_REPLAY_BUFFER_SIZE = 100;
796
+ var DEFAULT_REPLAY_TTL_MS = 3e5;
797
+ var DEFAULT_REPLAY_MAX_IDLE_USERS = 1e3;
496
798
  exports.EventReplayBuffer = class EventReplayBuffer {
497
799
  constructor(opts) {
498
800
  this.opts = opts;
499
801
  }
500
802
  opts;
501
- buffers = /* @__PURE__ */ new Map();
803
+ rings = /* @__PURE__ */ new Map();
804
+ idle = /* @__PURE__ */ new Map();
805
+ open(userId) {
806
+ this.sweep();
807
+ let ring = this.rings.get(userId);
808
+ if (!ring) {
809
+ ring = { events: [], live: 0 };
810
+ this.rings.set(userId, ring);
811
+ }
812
+ ring.live += 1;
813
+ this.idle.delete(userId);
814
+ }
815
+ close(userId) {
816
+ const ring = this.rings.get(userId);
817
+ if (!ring || ring.live === 0) return;
818
+ ring.live -= 1;
819
+ if (ring.live > 0) return;
820
+ this.idle.set(userId, performance.now());
821
+ const max = this.opts.sse?.replayMaxIdleUsers ?? DEFAULT_REPLAY_MAX_IDLE_USERS;
822
+ for (const oldest of this.idle.keys()) {
823
+ if (this.idle.size <= max) break;
824
+ this.drop(oldest);
825
+ }
826
+ }
502
827
  append(userId, event) {
503
- const buf = this.buffers.get(userId) ?? [];
504
- buf.push(event);
505
- const cap = this.opts.sse?.replayBufferSize ?? DEFAULT_REPLAY_BUFFER_SIZE;
506
- if (buf.length > cap) buf.shift();
507
- this.buffers.set(userId, buf);
828
+ this.sweep();
829
+ const ring = this.rings.get(userId);
830
+ if (!ring) return;
831
+ ring.events.push(event);
832
+ if (ring.events.length > (this.opts.sse?.replayBufferSize ?? DEFAULT_REPLAY_BUFFER_SIZE)) {
833
+ ring.events.shift();
834
+ }
508
835
  }
509
836
  since(userId, lastEventId) {
510
- const buf = this.buffers.get(userId);
511
- if (!buf) return [];
512
- const idx = buf.findIndex((event) => event.id === lastEventId);
837
+ this.sweep();
838
+ const events = this.rings.get(userId)?.events;
839
+ if (!events) return [];
840
+ const idx = events.findIndex((event) => event.id === lastEventId);
513
841
  if (idx === -1) return [];
514
- return buf.slice(idx + 1);
842
+ return events.slice(idx + 1);
515
843
  }
516
844
  size(userId) {
517
- return this.buffers.get(userId)?.length ?? 0;
845
+ this.sweep();
846
+ return this.rings.get(userId)?.events.length ?? 0;
847
+ }
848
+ sweep() {
849
+ const ttl = this.opts.sse?.replayTtlMs ?? DEFAULT_REPLAY_TTL_MS;
850
+ const now = performance.now();
851
+ for (const [userId, closedAt] of this.idle) {
852
+ if (now - closedAt < ttl) break;
853
+ this.drop(userId);
854
+ }
855
+ }
856
+ drop(userId) {
857
+ this.rings.delete(userId);
858
+ this.idle.delete(userId);
518
859
  }
519
860
  };
520
861
  exports.EventReplayBuffer = __decorateClass([
@@ -524,7 +865,7 @@ exports.EventReplayBuffer = __decorateClass([
524
865
  var KEEPALIVE_COMMENT = ": keepalive\n\n";
525
866
  exports.HeartbeatService = class HeartbeatService {
526
867
  timers = /* @__PURE__ */ new Map();
527
- start(connectionId, res, intervalMs) {
868
+ start(connectionId, res, intervalMs, onTick) {
528
869
  if (intervalMs < HEARTBEAT_MIN_MS || intervalMs > HEARTBEAT_MAX_MS) {
529
870
  throw realtimeError(
530
871
  REALTIME_ERROR_CODES.INVALID_OPTIONS,
@@ -535,6 +876,7 @@ exports.HeartbeatService = class HeartbeatService {
535
876
  const timer = setInterval(() => {
536
877
  try {
537
878
  res.write(KEEPALIVE_COMMENT);
879
+ onTick?.();
538
880
  } catch {
539
881
  this.stop(connectionId);
540
882
  }
@@ -558,45 +900,149 @@ exports.HeartbeatService = __decorateClass([
558
900
  common.Injectable()
559
901
  ], exports.HeartbeatService);
560
902
 
903
+ // src/server/transports/sse/frame-size.ts
904
+ var EVENT_FIELD = "event: ".length + "\n".length;
905
+ var ID_FIELD = "id: ".length + "\n".length;
906
+ var DATA_FIELD = "data: ".length + "\n".length;
907
+ var FRAME_END = "\n".length;
908
+ var sizes = /* @__PURE__ */ new WeakMap();
909
+ function fieldBytes(value) {
910
+ return Buffer.byteLength(value.replace(/[\r\n]/g, ""));
911
+ }
912
+ function frameBytes(message) {
913
+ let size = sizes.get(message);
914
+ if (size === void 0) {
915
+ const { data, type, id } = message;
916
+ size = FRAME_END + ID_FIELD + fieldBytes(id);
917
+ if (type) size += EVENT_FIELD + fieldBytes(type);
918
+ if (data !== void 0 && data !== null) {
919
+ size += DATA_FIELD + Buffer.byteLength(typeof data === "string" ? data : JSON.stringify(data) ?? "");
920
+ }
921
+ sizes.set(message, size);
922
+ }
923
+ return size;
924
+ }
925
+
926
+ // src/server/transports/sse/outbound-backlog.ts
927
+ function probeOf(res) {
928
+ if (typeof res.socket?.bytesWritten !== "number") return void 0;
929
+ return {
930
+ written: () => (res.socket?.bytesWritten ?? 0) - (res.socket?.writableLength ?? 0),
931
+ buffered: () => Math.max(res.writableLength ?? 0, res.socket?.writableLength ?? 0)
932
+ };
933
+ }
934
+ var OutboundBacklog = class {
935
+ constructor(limits, probe) {
936
+ this.limits = limits;
937
+ this.probe = probe;
938
+ this.baseline = probe.written();
939
+ }
940
+ limits;
941
+ probe;
942
+ ends = [];
943
+ head = 0;
944
+ sent = 0;
945
+ baseline;
946
+ get queuedBytes() {
947
+ this.settle();
948
+ return this.pendingBytes();
949
+ }
950
+ get retained() {
951
+ return this.ends.length;
952
+ }
953
+ get queuedEvents() {
954
+ this.settle();
955
+ return this.ends.length - this.head;
956
+ }
957
+ admit(size) {
958
+ this.settle();
959
+ const { maxBytes, maxEvents } = this.limits;
960
+ const queued = this.ends.length - this.head;
961
+ if (maxBytes > 0 && queued > 0 && this.pendingBytes() + size > maxBytes) return false;
962
+ if (maxEvents > 0 && queued + 1 > maxEvents) return false;
963
+ this.sent += size;
964
+ this.ends.push(this.sent);
965
+ return true;
966
+ }
967
+ pendingBytes() {
968
+ return Math.max(0, this.sent - this.settledOffset());
969
+ }
970
+ settledOffset() {
971
+ return Math.max(0, this.probe.written() - this.baseline);
972
+ }
973
+ settle() {
974
+ const settled = this.settledOffset();
975
+ while (this.head < this.ends.length && this.ends[this.head] <= settled) this.head++;
976
+ if (this.head === this.ends.length) {
977
+ this.ends = [];
978
+ this.head = 0;
979
+ this.sent = 0;
980
+ this.baseline = this.probe.written();
981
+ } else if (this.head > 1024 && this.head * 2 > this.ends.length) {
982
+ this.ends = this.ends.slice(this.head);
983
+ this.head = 0;
984
+ }
985
+ }
986
+ };
987
+ var StallWatch = class {
988
+ constructor(checks) {
989
+ this.checks = checks;
990
+ }
991
+ checks;
992
+ last = -1;
993
+ stalledChecks = 0;
994
+ stalled(probe) {
995
+ if (this.checks <= 0) return false;
996
+ const written = probe.written();
997
+ const stuck = probe.buffered() > 0 && written === this.last;
998
+ this.last = written;
999
+ this.stalledChecks = stuck ? this.stalledChecks + 1 : 0;
1000
+ return this.stalledChecks >= this.checks;
1001
+ }
1002
+ };
1003
+
561
1004
  // src/server/transports/sse/sse.transport.ts
562
1005
  var _shuttingDown;
563
1006
  exports.SseTransport = class SseTransport {
564
- constructor(connections, rooms, replayBuffer, idGen, heartbeat, auth, pubsub, hooks, options, instanceId, offlineQueue) {
1007
+ constructor(connections, rooms, replayBuffer, idGen, heartbeat, gate, pubsub, hooks, options, instanceId, offlineQueue, admission) {
565
1008
  this.connections = connections;
566
1009
  this.rooms = rooms;
567
1010
  this.replayBuffer = replayBuffer;
568
1011
  this.idGen = idGen;
569
1012
  this.heartbeat = heartbeat;
570
- this.auth = auth;
1013
+ this.gate = gate;
571
1014
  this.pubsub = pubsub;
572
1015
  this.hooks = hooks;
573
1016
  this.options = options;
574
1017
  this.instanceId = instanceId;
575
1018
  this.offlineQueue = offlineQueue;
1019
+ this.admission = admission;
576
1020
  __publicField(this, "kind", "sse");
577
1021
  __publicField(this, "logger", new common.Logger(exports.SseTransport.name));
578
1022
  __privateAdd(this, _shuttingDown, false);
1023
+ __publicField(this, "outbound", /* @__PURE__ */ new Map());
579
1024
  }
580
1025
  connections;
581
1026
  rooms;
582
1027
  replayBuffer;
583
1028
  idGen;
584
1029
  heartbeat;
585
- auth;
1030
+ gate;
586
1031
  pubsub;
587
1032
  hooks;
588
1033
  options;
589
1034
  instanceId;
590
1035
  offlineQueue;
1036
+ admission;
591
1037
  onModuleDestroy() {
592
1038
  __privateSet(this, _shuttingDown, true);
593
1039
  }
594
1040
  async beforeApplicationShutdown() {
595
1041
  __privateSet(this, _shuttingDown, true);
596
1042
  this.heartbeat.stopAll();
597
- for (const conn of this.connections.allByTransport("sse")) {
598
- await this.disconnectLocal(conn.connectionId);
599
- }
1043
+ await Promise.all(
1044
+ this.connections.allByTransport("sse").map((conn) => this.disconnectLocal(conn.connectionId))
1045
+ );
600
1046
  }
601
1047
  async onApplicationShutdown() {
602
1048
  await this.beforeApplicationShutdown();
@@ -610,8 +1056,11 @@ exports.SseTransport = class SseTransport {
610
1056
  get emitConnectionEvent() {
611
1057
  return this.options.sse?.emitConnectionEvent !== false;
612
1058
  }
1059
+ admit() {
1060
+ return this.admission?.admit() ?? UNBOUNDED_TICKET;
1061
+ }
613
1062
  authenticate(context) {
614
- return this.auth.authenticate(context);
1063
+ return this.gate.authenticate(context);
615
1064
  }
616
1065
  async registerConnection(params) {
617
1066
  const record = {
@@ -633,6 +1082,8 @@ exports.SseTransport = class SseTransport {
633
1082
  }
634
1083
  };
635
1084
  this.connections.register(record);
1085
+ this.replayBuffer.open(params.auth.userId);
1086
+ this.track(params);
636
1087
  this.rooms.join(params.connectionId, composeRoomId("USER", params.auth.userId));
637
1088
  if (params.auth.tenantId !== void 0) {
638
1089
  this.rooms.join(params.connectionId, composeRoomId("TENANT", params.auth.tenantId));
@@ -641,12 +1092,20 @@ exports.SseTransport = class SseTransport {
641
1092
  await this.evictBeyondLimit(params.auth.userId);
642
1093
  }
643
1094
  async unregisterConnection(connectionId, reason) {
1095
+ const record = this.release(connectionId);
1096
+ if (record) await this.notifyDisconnect(record, reason);
1097
+ }
1098
+ release(connectionId) {
644
1099
  const record = this.connections.unregister(connectionId);
645
- if (!record) return;
1100
+ if (record) this.replayBuffer.close(record.userId);
646
1101
  this.rooms.leaveAll(connectionId);
647
1102
  this.heartbeat.stop(connectionId);
648
- try {
649
- await this.hooks.onDisconnect?.({
1103
+ this.outbound.delete(connectionId);
1104
+ return record;
1105
+ }
1106
+ async notifyDisconnect(record, reason) {
1107
+ const failed = await runHook(
1108
+ () => this.hooks.onDisconnect?.({
650
1109
  connectionId: record.connectionId,
651
1110
  userId: record.userId,
652
1111
  tenantId: record.tenantId,
@@ -658,10 +1117,10 @@ exports.SseTransport = class SseTransport {
658
1117
  connectedAt: record.connectedAt,
659
1118
  durationMs: Date.now() - record.connectedAt.getTime(),
660
1119
  ...reason !== void 0 ? { reason } : {}
661
- });
662
- } catch (error) {
663
- this.logger.error(`onDisconnect hook failed: ${describeError(error)}`);
664
- }
1120
+ }),
1121
+ this.options.hookTimeoutMs ?? DEFAULT_HOOK_TIMEOUT_MS
1122
+ );
1123
+ if (failed) this.logger.error(`onDisconnect hook failed: ${describeError(failed.error)}`);
665
1124
  }
666
1125
  getReplayEvents(userId, lastEventId) {
667
1126
  return this.replayBuffer.since(userId, lastEventId);
@@ -781,20 +1240,61 @@ exports.SseTransport = class SseTransport {
781
1240
  async disconnectLocal(connectionId, reason) {
782
1241
  const record = this.connections.get(connectionId);
783
1242
  if (!record || record.transport !== "sse") return;
784
- await this.unregisterConnection(connectionId, reason);
1243
+ const released = this.release(connectionId);
785
1244
  record.close$?.next();
786
1245
  record.close$?.complete();
1246
+ if (released) await this.notifyDisconnect(released, reason);
787
1247
  }
788
1248
  buildMessage(id, event, data) {
789
1249
  return { id, type: event, data };
790
1250
  }
791
1251
  deliver(conn, message) {
792
1252
  try {
1253
+ const tracked = this.outbound.get(conn.connectionId);
1254
+ if (tracked && !tracked.backlog.admit(frameBytes(message))) {
1255
+ this.cutSlowConsumer(conn.connectionId, "its client has not read what was sent", tracked);
1256
+ return;
1257
+ }
793
1258
  conn.subject?.next(message);
794
1259
  } catch (error) {
795
1260
  this.logger.warn(`SSE delivery failed for ${conn.connectionId}: ${describeError(error)}`);
796
1261
  }
797
1262
  }
1263
+ track(params) {
1264
+ const { outbound: probe } = params;
1265
+ const sse = this.options.sse;
1266
+ if (!probe) return;
1267
+ this.outbound.set(params.connectionId, {
1268
+ probe,
1269
+ backlog: new OutboundBacklog(
1270
+ { maxBytes: sse?.maxQueuedBytes ?? 0, maxEvents: sse?.maxQueuedEvents ?? 0 },
1271
+ probe
1272
+ ),
1273
+ stall: new StallWatch(sse?.stallHeartbeats ?? 0)
1274
+ });
1275
+ }
1276
+ checkStall(connectionId) {
1277
+ const tracked = this.outbound.get(connectionId);
1278
+ if (tracked?.stall.stalled(tracked.probe)) {
1279
+ this.cutSlowConsumer(
1280
+ connectionId,
1281
+ "its socket has taken nothing for several heartbeats",
1282
+ tracked
1283
+ );
1284
+ }
1285
+ }
1286
+ cutSlowConsumer(connectionId, why, tracked) {
1287
+ this.logger.warn(
1288
+ `${REALTIME_ERROR_CODES.SLOW_CONSUMER}: closing SSE connection ${connectionId}, ${why} (${tracked.backlog.queuedEvents} events, ${tracked.backlog.queuedBytes} bytes queued, ${tracked.probe.buffered()} bytes held by the response)`
1289
+ );
1290
+ this.disconnectLocal(connectionId, REALTIME_ERROR_CODES.SLOW_CONSUMER).catch(
1291
+ (error) => {
1292
+ this.logger.warn(
1293
+ `Closing slow SSE connection ${connectionId} failed: ${describeError(error)}`
1294
+ );
1295
+ }
1296
+ );
1297
+ }
798
1298
  async tryPublish(message) {
799
1299
  try {
800
1300
  await this.pubsub.publish({ ...message, origin: this.instanceId });
@@ -834,19 +1334,35 @@ exports.SseTransport = __decorateClass([
834
1334
  __decorateParam(2, common.Inject(exports.EventReplayBuffer)),
835
1335
  __decorateParam(3, common.Inject(exports.EventIdGenerator)),
836
1336
  __decorateParam(4, common.Inject(exports.HeartbeatService)),
837
- __decorateParam(5, common.Inject(REALTIME_AUTHENTICATOR_TOKEN)),
1337
+ __decorateParam(5, common.Inject(exports.AuthenticationGate)),
838
1338
  __decorateParam(6, common.Inject(REALTIME_PUBSUB_TOKEN)),
839
1339
  __decorateParam(7, common.Inject(REALTIME_HOOKS_TOKEN)),
840
1340
  __decorateParam(8, common.Inject(REALTIME_OPTIONS_TOKEN)),
841
1341
  __decorateParam(9, common.Inject(REALTIME_INSTANCE_ID_TOKEN)),
842
1342
  __decorateParam(10, common.Optional()),
843
- __decorateParam(10, common.Inject(REALTIME_OFFLINE_QUEUE_TOKEN))
1343
+ __decorateParam(10, common.Inject(REALTIME_OFFLINE_QUEUE_TOKEN)),
1344
+ __decorateParam(11, common.Optional()),
1345
+ __decorateParam(11, common.Inject(exports.ConnectionAdmission))
844
1346
  ], exports.SseTransport);
845
1347
 
1348
+ // src/server/transports/sse/response-close.ts
1349
+ function onResponseClose(res, listener) {
1350
+ const emitter = [res, res?.raw, res?.socket].find((candidate) => candidate?.once) ?? void 0;
1351
+ emitter?.once?.("close", listener);
1352
+ return () => void emitter?.off?.("close", listener);
1353
+ }
1354
+
846
1355
  // src/server/transports/sse/sse-subscription.handler.ts
847
1356
  function singleHeader(value) {
848
1357
  return typeof value === "string" ? value : void 0;
849
1358
  }
1359
+ var MAX_LAST_EVENT_ID_LENGTH = 256;
1360
+ function believedId(value) {
1361
+ return typeof value === "string" && value !== "" && value.length <= MAX_LAST_EVENT_ID_LENGTH ? value : void 0;
1362
+ }
1363
+ function lastEventIdOf(req) {
1364
+ return believedId(req.headers["last-event-id"]) ?? believedId(req.query["lastEventId"]);
1365
+ }
850
1366
  function normalizeHeaders(headers) {
851
1367
  const out = /* @__PURE__ */ Object.create(null);
852
1368
  for (const [key, value] of Object.entries(headers)) {
@@ -915,10 +1431,10 @@ exports.SseSubscriptionHandler = class SseSubscriptionHandler {
915
1431
  logger = new common.Logger(exports.SseSubscriptionHandler.name);
916
1432
  authenticated = /* @__PURE__ */ new WeakMap();
917
1433
  resolveAndValidateIdentity(auth) {
918
- const resolvedAuth = resolveAuthTenant(this.options, auth);
1434
+ let resolvedAuth = resolveAuthTenant(this.options, auth);
919
1435
  try {
920
1436
  assertIdentityIsNotBlank(resolvedAuth);
921
- assertAdmissionRooms(resolvedAuth);
1437
+ resolvedAuth = admitRooms(resolvedAuth);
922
1438
  } catch (err) {
923
1439
  this.logger.error(`SSE connection refused \u2014 responding 500: ${describeError(err)}`);
924
1440
  throw new common.InternalServerErrorException();
@@ -933,17 +1449,24 @@ exports.SseSubscriptionHandler = class SseSubscriptionHandler {
933
1449
  this.authenticated.delete(req);
934
1450
  let authenticated;
935
1451
  try {
936
- authenticated = done ?? await this.authenticateRequest(req);
1452
+ authenticated = done ?? await this.authenticateRequest(req, res);
937
1453
  } catch (err) {
938
1454
  throw this.toClientError(err, "SSE authentication failed");
939
1455
  }
940
- let stream;
1456
+ let queueEvents;
941
1457
  try {
942
- stream = await this.openStream(req, res, authenticated);
1458
+ queueEvents = await this.readAppended(req, authenticated);
943
1459
  } catch (err) {
944
- throw this.serverError(err, "SSE handshake failed");
1460
+ authenticated.ticket.release();
1461
+ throw err;
1462
+ }
1463
+ const stream = this.openStream(req, res, authenticated, queueEvents);
1464
+ try {
1465
+ this.refuseDuringShutdown();
1466
+ } catch (err) {
1467
+ authenticated.ticket.release();
1468
+ throw err;
945
1469
  }
946
- this.refuseDuringShutdown();
947
1470
  return stream;
948
1471
  }
949
1472
  refuseDuringShutdown() {
@@ -951,20 +1474,22 @@ exports.SseSubscriptionHandler = class SseSubscriptionHandler {
951
1474
  throw new common.ServiceUnavailableException(REALTIME_ERROR_CODES.TRANSPORT_UNAVAILABLE);
952
1475
  }
953
1476
  }
954
- async openStream(req, res, authenticated) {
955
- const { context, auth: resolvedAuth } = authenticated;
1477
+ openStream(req, res, authenticated, gapEvents) {
1478
+ const { context, auth: resolvedAuth, ticket } = authenticated;
956
1479
  const connectionId = crypto.randomUUID();
957
1480
  const subject = new rxjs.Subject();
958
1481
  const close$ = new rxjs.Subject();
959
- const lastEventId = singleHeader(req.headers["last-event-id"]);
1482
+ const lastEventId = lastEventIdOf(req);
960
1483
  const replayEvents = lastEventId ? this.transport.getReplayEvents(resolvedAuth.userId, lastEventId) : [];
1484
+ const queueEvents = gapEvents.filter(
1485
+ (queued) => !replayEvents.some((replayed) => replayed.id === queued.id)
1486
+ );
961
1487
  const replay$ = replayEvents.length > 0 ? rxjs.of(...replayEvents) : rxjs.EMPTY;
962
- const ringBufferIds = new Set(replayEvents.map((e) => e.id ?? ""));
963
- const queueEvents = lastEventId && this.offlineDelivery ? await this.offlineDelivery.retrieve(resolvedAuth.userId, lastEventId, ringBufferIds) : [];
964
1488
  const established$ = this.transport.emitConnectionEvent ? rxjs.of(buildEstablishedEvent(connectionId, resolvedAuth)) : rxjs.EMPTY;
965
1489
  return this.buildStream({
966
1490
  connectionId,
967
1491
  resolvedAuth,
1492
+ ticket,
968
1493
  ip: context.ip,
969
1494
  userAgent: context.userAgent,
970
1495
  res,
@@ -975,29 +1500,79 @@ exports.SseSubscriptionHandler = class SseSubscriptionHandler {
975
1500
  queueEvents
976
1501
  });
977
1502
  }
978
- async authenticateBeforeCommit(req) {
1503
+ async authenticateBeforeCommit(req, res) {
979
1504
  try {
980
- this.authenticated.set(req, await this.authenticateRequest(req));
1505
+ this.authenticated.set(req, await this.authenticateRequest(req, res));
981
1506
  } catch (err) {
982
1507
  throw this.toClientError(err, "SSE authentication failed");
983
1508
  }
984
1509
  }
985
1510
  toClientError(err, what) {
1511
+ if (err instanceof AuthenticationUnavailableError || err instanceof ConnectionLimitError) {
1512
+ return new common.ServiceUnavailableException();
1513
+ }
986
1514
  return err instanceof common.HttpException ? err : this.serverError(err, what);
987
1515
  }
988
1516
  serverError(err, what) {
989
1517
  this.logger.error(`${what} \u2014 responding 500: ${describeError(err)}`);
990
1518
  return new common.InternalServerErrorException();
991
1519
  }
992
- async authenticateRequest(req) {
993
- const context = buildAuthContext(req);
994
- const auth = await this.transport.authenticate(context);
995
- if (!auth) throw new common.UnauthorizedException(REALTIME_ERROR_CODES.AUTH_FAILED);
996
- return { context, auth: this.resolveAndValidateIdentity(auth) };
1520
+ async authenticateRequest(req, res) {
1521
+ const held = this.transport.admit();
1522
+ const detach = onResponseClose(res, () => ticket.release());
1523
+ const ticket = {
1524
+ release: () => {
1525
+ detach();
1526
+ held.release();
1527
+ },
1528
+ renew: () => held.renew()
1529
+ };
1530
+ try {
1531
+ const context = buildAuthContext(req);
1532
+ const auth = await this.transport.authenticate(context);
1533
+ if (!auth) throw new common.UnauthorizedException(REALTIME_ERROR_CODES.AUTH_FAILED);
1534
+ const resolved = this.resolveAndValidateIdentity(auth);
1535
+ return {
1536
+ context,
1537
+ auth: resolved,
1538
+ ticket,
1539
+ queueRead: await this.readQueue(req, resolved.userId)
1540
+ };
1541
+ } catch (err) {
1542
+ ticket.release();
1543
+ throw err;
1544
+ }
1545
+ }
1546
+ async readQueue(req, userId) {
1547
+ const lastEventId = lastEventIdOf(req);
1548
+ if (!lastEventId || !this.offlineDelivery) return { events: [], degraded: false };
1549
+ try {
1550
+ return await this.offlineDelivery.retrieveGap(userId, lastEventId);
1551
+ } catch (err) {
1552
+ if (err instanceof OfflineQueueTimeoutError) throw new common.ServiceUnavailableException();
1553
+ throw this.serverError(err, "SSE handshake failed");
1554
+ }
1555
+ }
1556
+ async readAppended(req, authenticated) {
1557
+ const lastEventId = lastEventIdOf(req);
1558
+ const { queueRead } = authenticated;
1559
+ if (!lastEventId || !this.offlineDelivery) return queueRead.events;
1560
+ try {
1561
+ const appended = await this.offlineDelivery.retrieveAppended(
1562
+ authenticated.auth.userId,
1563
+ lastEventId,
1564
+ queueRead
1565
+ );
1566
+ return [...queueRead.events, ...appended];
1567
+ } catch (err) {
1568
+ if (err instanceof OfflineQueueTimeoutError) throw new common.ServiceUnavailableException();
1569
+ throw this.serverError(err, "SSE handshake failed");
1570
+ }
997
1571
  }
998
1572
  buildStream(p) {
999
1573
  return new rxjs.Observable((subscriber) => {
1000
1574
  if (this.transport.shuttingDown) {
1575
+ p.ticket.release();
1001
1576
  subscriber.complete();
1002
1577
  return void 0;
1003
1578
  }
@@ -1028,7 +1603,23 @@ exports.SseSubscriptionHandler = class SseSubscriptionHandler {
1028
1603
  }
1029
1604
  activateConnection(p, subscriber) {
1030
1605
  const { connectionId, resolvedAuth, ip, userAgent, subject, close$ } = p;
1031
- this.transport.registerConnection({ connectionId, auth: resolvedAuth, subject, close$, ip, userAgent }).then(() => this.onRegistered(p, subscriber)).catch((err) => {
1606
+ try {
1607
+ p.ticket.renew();
1608
+ } catch (err) {
1609
+ subscriber.error(this.toClientError(err, "SSE registration refused"));
1610
+ return;
1611
+ }
1612
+ const registering = this.transport.registerConnection({
1613
+ connectionId,
1614
+ auth: resolvedAuth,
1615
+ subject,
1616
+ close$,
1617
+ ip,
1618
+ userAgent,
1619
+ outbound: probeOf(p.res)
1620
+ });
1621
+ p.ticket.release();
1622
+ registering.then(() => this.onRegistered(p, subscriber)).catch((err) => {
1032
1623
  this.fireHook(
1033
1624
  () => this.hooks?.onError?.({ connectionId, error: err, transport: "sse" })
1034
1625
  );
@@ -1047,11 +1638,16 @@ exports.SseSubscriptionHandler = class SseSubscriptionHandler {
1047
1638
  this.fireHook(() => this.hooks?.onConnect?.(buildMeta(record)));
1048
1639
  }
1049
1640
  const heartbeatMs = this.options.sse?.heartbeatMs ?? DEFAULT_HEARTBEAT_MS;
1050
- this.heartbeat.start(connectionId, res, heartbeatMs);
1641
+ this.heartbeat.start(
1642
+ connectionId,
1643
+ res,
1644
+ heartbeatMs,
1645
+ () => this.transport.checkStall(connectionId)
1646
+ );
1051
1647
  }
1052
1648
  fireHook(invoke) {
1053
- void Promise.resolve(invoke()).catch((err) => {
1054
- this.logger.warn(`Lifecycle hook failed: ${describeError(err)}`);
1649
+ void runHook(invoke).then((failed) => {
1650
+ if (failed) this.logger.warn(`Lifecycle hook failed: ${describeError(failed.error)}`);
1055
1651
  });
1056
1652
  }
1057
1653
  };
@@ -1080,7 +1676,11 @@ function createSseController(endpoint) {
1080
1676
  }
1081
1677
  handler;
1082
1678
  async canActivate(context) {
1083
- await this.handler.authenticateBeforeCommit(context.switchToHttp().getRequest());
1679
+ const http = context.switchToHttp();
1680
+ await this.handler.authenticateBeforeCommit(
1681
+ http.getRequest(),
1682
+ http.getResponse()
1683
+ );
1084
1684
  return true;
1085
1685
  }
1086
1686
  };
@@ -1148,11 +1748,35 @@ exports.RealtimeService = __decorateClass([
1148
1748
  __decorateParam(1, common.Optional()),
1149
1749
  __decorateParam(1, common.Inject(REALTIME_PUBSUB_TOKEN))
1150
1750
  ], exports.RealtimeService);
1751
+
1752
+ // src/server/utils/semaphore.ts
1753
+ var Semaphore = class {
1754
+ free;
1755
+ waiting = [];
1756
+ constructor(size) {
1757
+ this.free = size;
1758
+ }
1759
+ async run(task) {
1760
+ if (this.free > 0) this.free -= 1;
1761
+ else await new Promise((resolve) => this.waiting.push(resolve));
1762
+ try {
1763
+ return await task();
1764
+ } finally {
1765
+ const next = this.waiting.shift();
1766
+ if (next) next();
1767
+ else this.free += 1;
1768
+ }
1769
+ }
1770
+ };
1771
+
1772
+ // src/server/services/reauthentication.service.ts
1151
1773
  function resolvePolicy(raw) {
1152
1774
  return {
1153
1775
  intervalSeconds: raw?.intervalSeconds ?? 300,
1154
1776
  onFailure: raw?.onFailure ?? "disconnect",
1155
- cacheTtlMs: raw?.cacheTtlMs ?? 6e4
1777
+ cacheTtlMs: raw?.cacheTtlMs ?? 6e4,
1778
+ revalidateTimeoutMs: raw?.revalidateTimeoutMs ?? 1e4,
1779
+ concurrency: raw?.concurrency ?? 8
1156
1780
  };
1157
1781
  }
1158
1782
  exports.ReauthenticationService = class ReauthenticationService {
@@ -1162,6 +1786,7 @@ exports.ReauthenticationService = class ReauthenticationService {
1162
1786
  this.auth = auth;
1163
1787
  this.hooks = hooks;
1164
1788
  this.policy = resolvePolicy(options.reauthenticationPolicy);
1789
+ this.slots = new Semaphore(this.policy.concurrency);
1165
1790
  }
1166
1791
  connections;
1167
1792
  realtime;
@@ -1169,8 +1794,9 @@ exports.ReauthenticationService = class ReauthenticationService {
1169
1794
  hooks;
1170
1795
  logger = new common.Logger(exports.ReauthenticationService.name);
1171
1796
  timer = null;
1172
- positiveCache = /* @__PURE__ */ new Map();
1173
1797
  policy;
1798
+ inFlight = /* @__PURE__ */ new Set();
1799
+ slots;
1174
1800
  onModuleInit() {
1175
1801
  if (!this.auth.revalidate) {
1176
1802
  this.logger.log("Authenticator does not implement revalidate() \u2014 reauthentication disabled");
@@ -1189,7 +1815,6 @@ exports.ReauthenticationService = class ReauthenticationService {
1189
1815
  clearInterval(this.timer);
1190
1816
  this.timer = null;
1191
1817
  }
1192
- this.positiveCache.clear();
1193
1818
  }
1194
1819
  async runCycle() {
1195
1820
  const now = Date.now();
@@ -1197,32 +1822,66 @@ exports.ReauthenticationService = class ReauthenticationService {
1197
1822
  ...this.connections.allByTransport("sse"),
1198
1823
  ...this.connections.allByTransport("websocket")
1199
1824
  ];
1200
- for (const conn of connections) {
1201
- try {
1202
- const lastValid = this.positiveCache.get(conn.connectionId);
1203
- if (lastValid !== void 0 && now - lastValid < this.policy.cacheTtlMs) continue;
1204
- const originalAuth = {
1205
- userId: conn.originalAuth.userId,
1206
- ...conn.originalAuth.tenantId !== void 0 ? { tenantId: conn.originalAuth.tenantId } : {},
1207
- ...conn.originalAuth.roles !== void 0 ? { roles: conn.originalAuth.roles } : {},
1208
- ...conn.originalAuth.rooms !== void 0 ? { rooms: conn.originalAuth.rooms } : {},
1209
- ...conn.originalAuth.metadata !== void 0 ? { metadata: conn.originalAuth.metadata } : {}
1210
- };
1211
- const rawResult = await this.auth.revalidate?.(conn.connectionId, originalAuth) ?? true;
1212
- if (rawResult === true) {
1213
- this.positiveCache.set(conn.connectionId, now);
1214
- continue;
1215
- }
1216
- await this.revoke(conn);
1217
- } catch (err) {
1218
- this.logger.warn(`Reauthentication errored for ${conn.connectionId}: ${describeError(err)}`);
1219
- await this.revoke(conn);
1825
+ await Promise.all(connections.map((conn) => this.check(conn, now)));
1826
+ }
1827
+ async check(conn, now) {
1828
+ if (this.inFlight.has(conn.connectionId)) return;
1829
+ if (conn.revalidatedAt !== void 0 && now - conn.revalidatedAt < this.policy.cacheTtlMs)
1830
+ return;
1831
+ this.inFlight.add(conn.connectionId);
1832
+ try {
1833
+ await this.slots.run(() => this.revalidate(conn, now));
1834
+ } finally {
1835
+ this.inFlight.delete(conn.connectionId);
1836
+ }
1837
+ }
1838
+ async revalidate(conn, now) {
1839
+ const revalidate = this.auth.revalidate?.bind(this.auth);
1840
+ if (!revalidate) {
1841
+ conn.revalidatedAt = now;
1842
+ return;
1843
+ }
1844
+ try {
1845
+ const originalAuth = {
1846
+ userId: conn.originalAuth.userId,
1847
+ ...conn.originalAuth.tenantId !== void 0 ? { tenantId: conn.originalAuth.tenantId } : {},
1848
+ ...conn.originalAuth.roles !== void 0 ? { roles: conn.originalAuth.roles } : {},
1849
+ ...conn.originalAuth.rooms !== void 0 ? { rooms: conn.originalAuth.rooms } : {},
1850
+ ...conn.originalAuth.metadata !== void 0 ? { metadata: conn.originalAuth.metadata } : {}
1851
+ };
1852
+ const rawResult = await this.bounded(
1853
+ "revalidate",
1854
+ (signal) => revalidate(conn.connectionId, originalAuth, { signal })
1855
+ );
1856
+ if (rawResult === true) {
1857
+ conn.revalidatedAt = now;
1858
+ return;
1220
1859
  }
1860
+ await this.revoke(conn);
1861
+ } catch (err) {
1862
+ this.logger.warn(`Reauthentication errored for ${conn.connectionId}: ${describeError(err)}`);
1863
+ await this.revoke(conn);
1864
+ }
1865
+ }
1866
+ async bounded(what, work) {
1867
+ const controller = new AbortController();
1868
+ let timer;
1869
+ const timedOut = new Promise((_resolve, reject) => {
1870
+ timer = setTimeout(() => {
1871
+ reject(new Error(`${what} did not settle within ${this.policy.revalidateTimeoutMs} ms`));
1872
+ controller.abort();
1873
+ }, this.policy.revalidateTimeoutMs);
1874
+ timer.unref();
1875
+ });
1876
+ try {
1877
+ return await Promise.race([work(controller.signal), timedOut]);
1878
+ } finally {
1879
+ clearTimeout(timer);
1221
1880
  }
1222
1881
  }
1223
1882
  async revoke(conn) {
1224
1883
  try {
1225
- await this.handleFailure(conn);
1884
+ await this.bounded("revocation", () => this.handleFailure(conn));
1226
1885
  } catch (err) {
1227
1886
  this.logger.warn(
1228
1887
  `Revocation of ${conn.connectionId} failed, retrying next cycle: ${describeError(err)}`
@@ -1230,10 +1889,10 @@ exports.ReauthenticationService = class ReauthenticationService {
1230
1889
  }
1231
1890
  }
1232
1891
  async handleFailure(conn) {
1233
- this.positiveCache.delete(conn.connectionId);
1892
+ conn.revalidatedAt = void 0;
1234
1893
  if (this.policy.onFailure === "event") this.notify(conn);
1235
- void Promise.resolve(
1236
- this.hooks?.onReauthenticationFailed?.({
1894
+ void runHook(
1895
+ () => this.hooks?.onReauthenticationFailed?.({
1237
1896
  connectionId: conn.connectionId,
1238
1897
  userId: conn.userId,
1239
1898
  tenantId: conn.tenantId,
@@ -1244,8 +1903,10 @@ exports.ReauthenticationService = class ReauthenticationService {
1244
1903
  userAgent: conn.userAgent,
1245
1904
  connectedAt: conn.connectedAt
1246
1905
  })
1247
- ).catch((err) => {
1248
- this.logger.warn(`onReauthenticationFailed hook failed: ${describeError(err)}`);
1906
+ ).then((failed) => {
1907
+ if (failed) {
1908
+ this.logger.warn(`onReauthenticationFailed hook failed: ${describeError(failed.error)}`);
1909
+ }
1249
1910
  });
1250
1911
  await this.realtime.disconnect(conn.connectionId, REALTIME_ERROR_CODES.REAUTHENTICATION_FAILED);
1251
1912
  }
@@ -1296,7 +1957,9 @@ var SHARED_SERVICES = [
1296
1957
  exports.HeartbeatService,
1297
1958
  exports.RealtimeService,
1298
1959
  exports.ReauthenticationService,
1299
- exports.OfflineQueueDeliveryService
1960
+ exports.OfflineQueueDeliveryService,
1961
+ exports.AuthenticationGate,
1962
+ exports.ConnectionAdmission
1300
1963
  ];
1301
1964
  function assertModeSupported(wiring, mode, moduleName) {
1302
1965
  if (wiring.modes.includes(mode)) return;
@@ -1569,6 +2232,31 @@ exports.BymaxRealtimeModule = __decorateClass([
1569
2232
  common.Global(),
1570
2233
  common.Module({})
1571
2234
  ], exports.BymaxRealtimeModule);
2235
+
2236
+ // src/server/utils/quit-within.ts
2237
+ var QUIT_WAIT_MS = 2e3;
2238
+ async function quitWithin(client, ms = QUIT_WAIT_MS) {
2239
+ let timer;
2240
+ const bound = new Promise((resolve) => {
2241
+ timer = setTimeout(resolve, ms);
2242
+ timer.unref();
2243
+ });
2244
+ let answered = false;
2245
+ const quit = client.quit().then(
2246
+ () => {
2247
+ answered = true;
2248
+ },
2249
+ () => void 0
2250
+ );
2251
+ try {
2252
+ await Promise.race([quit, bound]);
2253
+ if (!answered) client.disconnect();
2254
+ } finally {
2255
+ clearTimeout(timer);
2256
+ }
2257
+ }
2258
+
2259
+ // src/server/pubsub/redis-realtime-pubsub.ts
1572
2260
  var MALFORMED_REPORT_INTERVAL_MS = 6e4;
1573
2261
  var CANNOT_PUBLISH = /* @__PURE__ */ new Set([
1574
2262
  "wait",
@@ -1656,7 +2344,7 @@ var RedisRealtimePubSub = class _RedisRealtimePubSub {
1656
2344
  const connected = this.#subscribed;
1657
2345
  this.#subscribed = false;
1658
2346
  try {
1659
- if (connected) await sub.quit();
2347
+ if (connected) await quitWithin(sub);
1660
2348
  else sub.disconnect();
1661
2349
  } catch {
1662
2350
  }
@@ -1671,7 +2359,11 @@ var RedisRealtimePubSub = class _RedisRealtimePubSub {
1671
2359
  this.#outageLogged = false;
1672
2360
  this.#lastRefusal = void 0;
1673
2361
  this.connectLazyClient();
1674
- const sub = this.#pub.duplicate({ autoResubscribe: false, enableOfflineQueue: true });
2362
+ const sub = this.#pub.duplicate({
2363
+ autoResubscribe: false,
2364
+ disconnectTimeout: 1,
2365
+ enableOfflineQueue: true
2366
+ });
1675
2367
  let attached = false;
1676
2368
  sub.on("message", (_ch, payload) => this.dispatch(payload));
1677
2369
  const unreachableFirst = new Promise((resolve) => {
@@ -1843,6 +2535,9 @@ var RedisOfflineQueue = class _RedisOfflineQueue {
1843
2535
  };
1844
2536
 
1845
2537
  exports.ADMISSION_ROOM_LIMITS = ADMISSION_ROOM_LIMITS;
2538
+ exports.AuthenticationUnavailableError = AuthenticationUnavailableError;
2539
+ exports.ConnectionLimitError = ConnectionLimitError;
2540
+ exports.DEFAULT_HOOK_TIMEOUT_MS = DEFAULT_HOOK_TIMEOUT_MS;
1846
2541
  exports.REALTIME_AUTHENTICATOR_TOKEN = REALTIME_AUTHENTICATOR_TOKEN;
1847
2542
  exports.REALTIME_ERROR_CODES = REALTIME_ERROR_CODES;
1848
2543
  exports.REALTIME_HOOKS_TOKEN = REALTIME_HOOKS_TOKEN;
@@ -1856,7 +2551,8 @@ exports.RESERVED_EVENT_NAMES = RESERVED_EVENT_NAMES;
1856
2551
  exports.ROOM_PREFIXES = ROOM_PREFIXES;
1857
2552
  exports.RedisOfflineQueue = RedisOfflineQueue;
1858
2553
  exports.RedisRealtimePubSub = RedisRealtimePubSub;
1859
- exports.assertAdmissionRooms = assertAdmissionRooms;
2554
+ exports.UNBOUNDED_TICKET = UNBOUNDED_TICKET;
2555
+ exports.admitRooms = admitRooms;
1860
2556
  exports.assertIdentityIsNotBlank = assertIdentityIsNotBlank;
1861
2557
  exports.composeForRoot = composeForRoot;
1862
2558
  exports.composeForRootAsync = composeForRootAsync;
@@ -1864,8 +2560,10 @@ exports.composeRoomId = composeRoomId;
1864
2560
  exports.createSseController = createSseController;
1865
2561
  exports.describeError = describeError;
1866
2562
  exports.parseCookieHeader = parseCookieHeader;
2563
+ exports.quitWithin = quitWithin;
1867
2564
  exports.realtimeError = realtimeError;
1868
2565
  exports.reportDeliveryFailure = reportDeliveryFailure;
1869
2566
  exports.resolveAuthTenant = resolveAuthTenant;
2567
+ exports.runHook = runHook;
1870
2568
  exports.sseWiring = sseWiring;
1871
2569
  exports.unavailableError = unavailableError;