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