@coasys/ad4m 0.13.1-staging.5 → 0.13.1-staging.6

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.
Files changed (33) hide show
  1. package/lib/index.cjs +421 -122
  2. package/lib/index.js +419 -123
  3. package/lib/src/Ad4mClient.d.ts +6 -0
  4. package/lib/src/Ad4mClient.js +8 -0
  5. package/lib/src/apiClient.d.ts +32 -0
  6. package/lib/src/apiClient.js +132 -13
  7. package/lib/src/model/Ad4mModel.d.ts +7 -0
  8. package/lib/src/model/Ad4mModel.js +16 -13
  9. package/lib/src/model/ModelQueryBuilder.d.ts +2 -0
  10. package/lib/src/model/ModelQueryBuilder.js +36 -57
  11. package/lib/src/perspectives/LiveQuery.d.ts +40 -4
  12. package/lib/src/perspectives/LiveQuery.js +94 -10
  13. package/lib/src/perspectives/PerspectiveClient.d.ts +4 -2
  14. package/lib/src/perspectives/PerspectiveClient.js +6 -4
  15. package/lib/src/perspectives/PerspectiveProxy.d.ts +15 -3
  16. package/lib/src/perspectives/PerspectiveProxy.js +33 -16
  17. package/lib/src/perspectives/WakerSubscriptionManager.d.ts +35 -2
  18. package/lib/src/perspectives/WakerSubscriptionManager.js +93 -9
  19. package/package.json +2 -2
  20. package/src/Ad4mClient.ts +9 -0
  21. package/src/apiClient.test.ts +467 -3
  22. package/src/apiClient.ts +133 -13
  23. package/src/model/Ad4mModel.test.ts +128 -364
  24. package/src/model/Ad4mModel.ts +16 -17
  25. package/src/model/ModelQueryBuilder.ts +39 -59
  26. package/src/model/write-round-trips.test.ts +215 -0
  27. package/src/perspectives/LiveQuery.test.ts +173 -1
  28. package/src/perspectives/LiveQuery.ts +110 -10
  29. package/src/perspectives/PerspectiveClient.ts +6 -4
  30. package/src/perspectives/PerspectiveProxy.test.ts +24 -2
  31. package/src/perspectives/PerspectiveProxy.ts +35 -16
  32. package/src/perspectives/WakerSubscriptionManager.test.ts +225 -1
  33. package/src/perspectives/WakerSubscriptionManager.ts +97 -10
package/lib/index.js CHANGED
@@ -129,6 +129,34 @@ const MAX_RECONNECT_DELAY_MS = 30000;
129
129
  * MAX_WATCH_RETRIES times in a row. */
130
130
  const WATCH_RETRY_DELAY_MS = 1000;
131
131
  const MAX_WATCH_RETRIES = 5;
132
+ /** An open socket sends a ping this often, and must deliver some message
133
+ * (the pong will do) within an interval of the first ping it left
134
+ * unanswered. After a network switch a socket can stay OPEN for minutes with
135
+ * no close event, since no FIN or RST ever arrives; this notices it within
136
+ * two intervals. */
137
+ const PING_INTERVAL_MS = 10000;
138
+ /** The slowest link a socket is given time for. The executor reads a ping
139
+ * only after the frames sent before it, so a ping left unanswered counts as
140
+ * silence only once everything the socket sent before that ping could have
141
+ * crossed this link and PONG_RETURN_MS more have passed, if that takes longer
142
+ * than PING_INTERVAL_MS. Messages that come in meanwhile do not shorten this:
143
+ * they say nothing about how far an upload has got. */
144
+ const SLOWEST_LINK_BYTES_PER_MS = 16; // 16 kB/s
145
+ /** How long a pong gets to come back after its ping could have been read
146
+ * behind a large write. Shorter than PING_INTERVAL_MS, so the few ms a small
147
+ * frame adds before a ping on an idle socket never cost a ping interval. */
148
+ const PONG_RETURN_MS = 5000;
149
+ /** The bytes `text` takes as UTF-8, as a WebSocket text frame sends it. */
150
+ function utf8Length(text) {
151
+ let bytes = text.length;
152
+ for (let i = 0; i < text.length; i++) {
153
+ const unit = text.charCodeAt(i);
154
+ // A surrogate is half of a 4-byte pair: 2 units, 2 extra bytes.
155
+ if (unit >= 0x80)
156
+ bytes += unit < 0x800 || (unit >= 0xd800 && unit <= 0xdfff) ? 1 : 2;
157
+ }
158
+ return bytes;
159
+ }
132
160
  let _idCounter = 0;
133
161
  function nextId() {
134
162
  return String(++_idCounter);
@@ -163,6 +191,14 @@ class ApiClient {
163
191
  this._wsReconnectTimer = null;
164
192
  this._wsReconnectDelay = INITIAL_RECONNECT_DELAY_MS;
165
193
  this._wsPingTimer = null;
194
+ /** When the open socket was first pinged since it last delivered a message; null while none is unanswered. */
195
+ this._wsPingedAt = null;
196
+ /** When that ping could have reached the executor, which reads it only after what the socket sent before it. */
197
+ this._wsPingArrivesBy = 0;
198
+ /** When everything the open socket sent so far could have crossed a SLOWEST_LINK_BYTES_PER_MS link.
199
+ * A message from the socket does not move it back: hearing from the executor says nothing
200
+ * about how much of a large upload has reached it. */
201
+ this._wsSentBy = 0;
166
202
  // The executor sends a socket only the events it asked for (`events.watch`).
167
203
  // What the executor has for the open socket, as sent; a new socket has `{}`.
168
204
  this._watching = '{}';
@@ -172,6 +208,13 @@ class ApiClient {
172
208
  this._watchSent = Promise.resolve();
173
209
  this._watchRetries = 0;
174
210
  this._watchRetryTimer = null;
211
+ this._wakeListening = false;
212
+ /** `online` always; `visibilitychange` only when the page became visible. */
213
+ this._onWake = (event) => {
214
+ if (event.type === 'visibilitychange' && typeof document !== 'undefined' && document.visibilityState !== 'visible')
215
+ return;
216
+ this.reconnectNow();
217
+ };
175
218
  this.baseUrl = baseUrl;
176
219
  this.token = token;
177
220
  this._webSocketImpl = webSocketImpl;
@@ -195,6 +238,9 @@ class ApiClient {
195
238
  return;
196
239
  if (this._authFailed !== null)
197
240
  throw new RpcError(401, this._authFailed);
241
+ // A dial ends any wait for one: a call or subscriber that dials during the backoff
242
+ // leaves no timer behind to swallow the retry after this socket's own drop.
243
+ this._cancelReconnect();
198
244
  const WsImpl = this._webSocketImpl ?? globalThis.WebSocket;
199
245
  const ws = new WsImpl(this._getWsUrl());
200
246
  this._ws = ws;
@@ -219,6 +265,8 @@ class ApiClient {
219
265
  // Only watchApplied() awaits this; a close before open is not an error otherwise.
220
266
  this._wsOpen.catch(() => { });
221
267
  ws.onmessage = (event) => {
268
+ if (this._ws === ws)
269
+ this._wsPingedAt = null;
222
270
  let parsed;
223
271
  try {
224
272
  parsed = JSON.parse(event.data);
@@ -244,7 +292,8 @@ class ApiClient {
244
292
  this._failAuth(rpcError.body);
245
293
  return;
246
294
  }
247
- if (parsed.type === 'pong')
295
+ // A dropped socket's events are not this client's any more: its successor watches again.
296
+ if (parsed.type === 'pong' || this._ws !== ws)
248
297
  return;
249
298
  const perspective = parsed.perspectiveUuid;
250
299
  const regs = this._handlers.get(parsed.type);
@@ -267,14 +316,14 @@ class ApiClient {
267
316
  if (this._ws !== ws)
268
317
  return;
269
318
  this._wsReconnectDelay = INITIAL_RECONNECT_DELAY_MS;
270
- this._startPing();
319
+ this._startPing(ws);
271
320
  // The watch goes out before the queued calls, so the events they cause reach listeners.
272
321
  this._watching = '{}';
273
322
  this._watchRetries = 0;
274
323
  this._flushWatch();
275
324
  for (const pending of this._pendingCalls.values()) {
276
325
  if (!pending.sent) {
277
- ws.send(pending.message);
326
+ this._send(ws, pending.message);
278
327
  pending.sent = true;
279
328
  }
280
329
  }
@@ -325,13 +374,40 @@ class ApiClient {
325
374
  for (const cb of [...this._authFailedCallbacks])
326
375
  callSafely(cb, 'Error in auth-failed callback:', reason);
327
376
  }
328
- _startPing() {
377
+ _startPing(ws) {
329
378
  this._stopPing();
379
+ this._wsPingedAt = null;
380
+ this._wsSentBy = 0;
330
381
  this._wsPingTimer = setInterval(() => {
331
- if (this._ws?.readyState === 1 /* OPEN */) {
332
- this._ws.send(JSON.stringify({ type: 'ping' }));
382
+ if (this._ws !== ws)
383
+ return;
384
+ const ping = JSON.stringify({ type: 'ping' });
385
+ if (this._wsPingedAt === null) {
386
+ this._wsPingedAt = performance.now();
387
+ this._send(ws, ping);
388
+ this._wsPingArrivesBy = this._wsSentBy;
389
+ return;
390
+ }
391
+ if (performance.now() >= Math.max(this._wsPingedAt + PING_INTERVAL_MS, this._wsPingArrivesBy + PONG_RETURN_MS)) {
392
+ this._dropSilentSocket(ws);
393
+ return;
333
394
  }
334
- }, 30000);
395
+ this._send(ws, ping);
396
+ }, PING_INTERVAL_MS);
397
+ }
398
+ /** Send on `ws`, counting how long what the open socket sent could take to cross the slowest link. */
399
+ _send(ws, text) {
400
+ if (this._ws === ws)
401
+ this._wsSentBy = Math.max(this._wsSentBy, performance.now()) + utf8Length(text) / SLOWEST_LINK_BYTES_PER_MS;
402
+ ws.send(text);
403
+ }
404
+ /** The socket answered nothing for a whole ping interval: treat it as
405
+ * closed now. Its close event can take minutes on a dead connection,
406
+ * since the close frame gets no answer either; `_onClose` ignores it then. */
407
+ _dropSilentSocket(ws) {
408
+ console.warn(`WebSocket silent for ${performance.now() - (this._wsPingedAt ?? performance.now())} ms after a ping; reconnecting`);
409
+ this._onClose(ws);
410
+ ws.close();
335
411
  }
336
412
  _stopPing() {
337
413
  if (this._wsPingTimer) {
@@ -346,8 +422,54 @@ class ApiClient {
346
422
  this._wsReconnectDelay = Math.min(this._wsReconnectDelay * 2, MAX_RECONNECT_DELAY_MS);
347
423
  this._wsReconnectTimer = setTimeout(() => {
348
424
  this._wsReconnectTimer = null;
425
+ this._listenForWake(false);
349
426
  this._ensureWs();
350
427
  }, delay);
428
+ this._listenForWake(true);
429
+ }
430
+ /** End the wait for the next dial, if one is pending, without dialling. */
431
+ _cancelReconnect() {
432
+ if (this._wsReconnectTimer) {
433
+ clearTimeout(this._wsReconnectTimer);
434
+ this._wsReconnectTimer = null;
435
+ }
436
+ this._listenForWake(false);
437
+ }
438
+ /**
439
+ * Dial now if the client is waiting out its reconnect backoff (up to 30 s)
440
+ * instead of letting the wait run out. For the moments the host knows the
441
+ * executor may be reachable again: an executor it restarted is up, the
442
+ * device woke. In a browser the client does this itself on `online` and when
443
+ * the page becomes visible. Does nothing while a socket is open or
444
+ * connecting, after `closeAll()` with nothing to reconnect, or once the
445
+ * executor refused the token.
446
+ */
447
+ reconnectNow() {
448
+ if (!this._wsReconnectTimer || this._ws || this._authFailed !== null)
449
+ return;
450
+ this._cancelReconnect();
451
+ // The executor is likely back, so a failure now starts the backoff over.
452
+ this._wsReconnectDelay = INITIAL_RECONNECT_DELAY_MS;
453
+ this._ensureWs();
454
+ }
455
+ /** Listen for `online` and `visibilitychange` exactly while a reconnect
456
+ * timer is pending. Outside a browser (no `window`) it registers nothing. */
457
+ _listenForWake(on) {
458
+ if (on === this._wakeListening)
459
+ return;
460
+ const win = typeof window !== 'undefined' ? window : undefined;
461
+ if (typeof win?.addEventListener !== 'function')
462
+ return;
463
+ const doc = typeof document !== 'undefined' && typeof document.addEventListener === 'function' ? document : undefined;
464
+ this._wakeListening = on;
465
+ if (on) {
466
+ win.addEventListener('online', this._onWake);
467
+ doc?.addEventListener('visibilitychange', this._onWake);
468
+ }
469
+ else {
470
+ win.removeEventListener('online', this._onWake);
471
+ doc?.removeEventListener('visibilitychange', this._onWake);
472
+ }
351
473
  }
352
474
  // ── RPC call method ─────────────────────────────────────────────────────
353
475
  /**
@@ -393,7 +515,7 @@ class ApiClient {
393
515
  }, timeoutMs);
394
516
  const onAbort = () => {
395
517
  if (pending.sent && this._ws?.readyState === 1 /* OPEN */) {
396
- this._ws.send(JSON.stringify({ id: nextId(), type: 'request.cancel', params: { targetId: id } }));
518
+ this._send(this._ws, JSON.stringify({ id: nextId(), type: 'request.cancel', params: { targetId: id } }));
397
519
  }
398
520
  settle(() => reject(new DOMException('Aborted', 'AbortError')));
399
521
  };
@@ -416,7 +538,7 @@ class ApiClient {
416
538
  return;
417
539
  }
418
540
  if (this._ws.readyState === 1 /* OPEN */) {
419
- this._ws.send(message);
541
+ this._send(this._ws, message);
420
542
  pending.sent = true;
421
543
  }
422
544
  });
@@ -537,10 +659,7 @@ class ApiClient {
537
659
  clearTimeout(this._watchRetryTimer);
538
660
  this._watchRetryTimer = null;
539
661
  }
540
- if (this._wsReconnectTimer) {
541
- clearTimeout(this._wsReconnectTimer);
542
- this._wsReconnectTimer = null;
543
- }
662
+ this._cancelReconnect();
544
663
  const ws = this._ws;
545
664
  this._ws = null;
546
665
  this._wsOpen = null;
@@ -6689,7 +6808,19 @@ var __classPrivateFieldGet$7 = (undefined && undefined.__classPrivateFieldGet) |
6689
6808
  if (typeof state === "function" ? receiver !== state || !f : !state.has(receiver)) throw new TypeError("Cannot read private member from an object whose class did not declare it");
6690
6809
  return kind === "m" ? f : kind === "a" ? f.call(receiver) : f ? f.value : state.get(receiver);
6691
6810
  };
6692
- var _LiveQuery_instances, _LiveQuery_client, _LiveQuery_uuid, _LiveQuery_open, _LiveQuery_onResult, _LiveQuery_id, _LiveQuery_revision, _LiveQuery_result, _LiveQuery_started, _LiveQuery_disposed, _LiveQuery_generation, _LiveQuery_latest, _LiveQuery_buffer, _LiveQuery_unlisten, _LiveQuery_unreconnect, _LiveQuery_start, _LiveQuery_replace, _LiveQuery_receive, _LiveQuery_resync;
6811
+ var _LiveQuery_instances, _LiveQuery_client, _LiveQuery_uuid, _LiveQuery_open, _LiveQuery_onResult, _LiveQuery_id, _LiveQuery_revision, _LiveQuery_result, _LiveQuery_started, _LiveQuery_disposed, _LiveQuery_generation, _LiveQuery_latest, _LiveQuery_buffer, _LiveQuery_unlisten, _LiveQuery_unreconnect, _LiveQuery_opening, _LiveQuery_retryTimer, _LiveQuery_reopening, _LiveQuery_statusListeners, _LiveQuery_start, _LiveQuery_reopen, _LiveQuery_clearRetry, _LiveQuery_emit, _LiveQuery_replace, _LiveQuery_receive, _LiveQuery_resync;
6812
+ /** Delay before the first retry of a failed re-open; it doubles per failure. */
6813
+ const REOPEN_BASE_DELAY_MS = 1000;
6814
+ /** Longest delay between two re-open attempts. */
6815
+ const REOPEN_MAX_DELAY_MS = 60000;
6816
+ /** The delay before re-open attempt `failures + 1`: between half and all of
6817
+ * `REOPEN_BASE_DELAY_MS * 2^(failures - 1)`, capped at
6818
+ * `REOPEN_MAX_DELAY_MS`. The random half spreads the clients of a restarted
6819
+ * executor apart. */
6820
+ function reopenDelay(failures, random = Math.random) {
6821
+ const ceiling = Math.min(REOPEN_BASE_DELAY_MS * 2 ** Math.max(0, failures - 1), REOPEN_MAX_DELAY_MS);
6822
+ return ceiling / 2 + random() * ceiling / 2;
6823
+ }
6693
6824
  /** Apply one update to the last result. Query rows are a multiset: added rows are appended.
6694
6825
  * Throws when the update names an instance that neither the last result nor
6695
6826
  * the update holds: the last result was wrong, and the caller must resync. */
@@ -6726,10 +6857,14 @@ function applyUpdate(result, update) {
6726
6857
  * One live query on the executor. Holds the last result, applies each update
6727
6858
  * to it, calls `resyncSubscription` when a revision is missing, and opens a
6728
6859
  * new subscription after a reconnect (the executor ends a socket's
6729
- * subscriptions when it closes). `onResult` gets every result after the
6730
- * first; `start()` returns the first.
6860
+ * subscriptions when it closes). A re-open that fails (the executor is
6861
+ * still loading the perspective after a restart) is retried with backoff
6862
+ * until it succeeds or the query is disposed; `onStatus` listeners hear
6863
+ * about it (#1595). `onResult` gets every result after the first; `start()`
6864
+ * returns the first.
6731
6865
  */
6732
6866
  class LiveQuery {
6867
+ /** `open` subscribes on the executor; aborting its signal cancels the call. */
6733
6868
  constructor(client, uuid, open, onResult) {
6734
6869
  _LiveQuery_instances.add(this);
6735
6870
  _LiveQuery_client.set(this, void 0);
@@ -6747,45 +6882,73 @@ class LiveQuery {
6747
6882
  _LiveQuery_buffer.set(this, null);
6748
6883
  _LiveQuery_unlisten.set(this, void 0);
6749
6884
  _LiveQuery_unreconnect.set(this, void 0);
6885
+ // Aborts the subscribe call still in flight, for `dispose({ cancelOpening })`.
6886
+ _LiveQuery_opening.set(this, void 0);
6887
+ _LiveQuery_retryTimer.set(this, void 0);
6888
+ _LiveQuery_reopening.set(this, false);
6889
+ _LiveQuery_statusListeners.set(this, new Set()
6890
+ /** `open` subscribes on the executor; aborting its signal cancels the call. */
6891
+ );
6750
6892
  __classPrivateFieldSet$7(this, _LiveQuery_client, client, "f");
6751
6893
  __classPrivateFieldSet$7(this, _LiveQuery_uuid, uuid, "f");
6752
6894
  __classPrivateFieldSet$7(this, _LiveQuery_open, open, "f");
6753
6895
  __classPrivateFieldSet$7(this, _LiveQuery_onResult, onResult, "f");
6754
6896
  __classPrivateFieldSet$7(this, _LiveQuery_unlisten, client.onQueryUpdate(update => __classPrivateFieldGet$7(this, _LiveQuery_instances, "m", _LiveQuery_receive).call(this, update)), "f");
6755
- __classPrivateFieldSet$7(this, _LiveQuery_unreconnect, client.onReconnect(() => {
6756
- this.start().catch(e => console.error('Error re-opening live query after reconnect:', e));
6757
- }), "f");
6897
+ __classPrivateFieldSet$7(this, _LiveQuery_unreconnect, client.onReconnect(() => __classPrivateFieldGet$7(this, _LiveQuery_instances, "m", _LiveQuery_reopen).call(this)), "f");
6758
6898
  }
6759
6899
  get id() { return __classPrivateFieldGet$7(this, _LiveQuery_id, "f"); }
6760
6900
  get result() { return __classPrivateFieldGet$7(this, _LiveQuery_result, "f"); }
6901
+ /** Whether a re-open failed and the query is waiting to retry it. */
6902
+ get reopening() { return __classPrivateFieldGet$7(this, _LiveQuery_reopening, "f"); }
6903
+ /** Call `listener` on each failed re-open and when a re-open succeeds
6904
+ * after one failed. Returns a remover. */
6905
+ onStatus(listener) {
6906
+ __classPrivateFieldGet$7(this, _LiveQuery_statusListeners, "f").add(listener);
6907
+ return () => __classPrivateFieldGet$7(this, _LiveQuery_statusListeners, "f").delete(listener);
6908
+ }
6761
6909
  /** Open the subscription (again) and return its initial result. A start
6762
6910
  * that a newer one overtakes resolves with the newer one's result. */
6763
6911
  start() {
6764
6912
  var _a;
6913
+ __classPrivateFieldGet$7(this, _LiveQuery_instances, "m", _LiveQuery_clearRetry).call(this);
6765
6914
  __classPrivateFieldSet$7(this, _LiveQuery_latest, __classPrivateFieldGet$7(this, _LiveQuery_instances, "m", _LiveQuery_start).call(this, __classPrivateFieldSet$7(this, _LiveQuery_generation, (_a = __classPrivateFieldGet$7(this, _LiveQuery_generation, "f"), ++_a), "f")), "f");
6766
6915
  return __classPrivateFieldGet$7(this, _LiveQuery_latest, "f");
6767
6916
  }
6768
- dispose() {
6917
+ /** End the subscription. With `cancelOpening`, a subscribe call still in
6918
+ * flight is cancelled too, so the executor stops computing a first result
6919
+ * nobody waits for (#1595); the pending `start()` then rejects instead of
6920
+ * resolving with that result. */
6921
+ dispose(options = {}) {
6769
6922
  var _a;
6770
6923
  __classPrivateFieldSet$7(this, _LiveQuery_disposed, true, "f");
6771
6924
  __classPrivateFieldSet$7(this, _LiveQuery_generation, (_a = __classPrivateFieldGet$7(this, _LiveQuery_generation, "f"), _a++, _a), "f");
6925
+ __classPrivateFieldGet$7(this, _LiveQuery_instances, "m", _LiveQuery_clearRetry).call(this);
6926
+ __classPrivateFieldGet$7(this, _LiveQuery_statusListeners, "f").clear();
6772
6927
  __classPrivateFieldGet$7(this, _LiveQuery_unlisten, "f").call(this);
6773
6928
  __classPrivateFieldGet$7(this, _LiveQuery_unreconnect, "f").call(this);
6929
+ if (options.cancelOpening)
6930
+ __classPrivateFieldGet$7(this, _LiveQuery_opening, "f")?.abort();
6774
6931
  if (__classPrivateFieldGet$7(this, _LiveQuery_id, "f"))
6775
6932
  __classPrivateFieldGet$7(this, _LiveQuery_client, "f").disposeQuerySubscription(__classPrivateFieldGet$7(this, _LiveQuery_uuid, "f"), __classPrivateFieldGet$7(this, _LiveQuery_id, "f")).catch(() => { });
6776
6933
  }
6777
6934
  }
6778
- _LiveQuery_client = new WeakMap(), _LiveQuery_uuid = new WeakMap(), _LiveQuery_open = new WeakMap(), _LiveQuery_onResult = new WeakMap(), _LiveQuery_id = new WeakMap(), _LiveQuery_revision = new WeakMap(), _LiveQuery_result = new WeakMap(), _LiveQuery_started = new WeakMap(), _LiveQuery_disposed = new WeakMap(), _LiveQuery_generation = new WeakMap(), _LiveQuery_latest = new WeakMap(), _LiveQuery_buffer = new WeakMap(), _LiveQuery_unlisten = new WeakMap(), _LiveQuery_unreconnect = new WeakMap(), _LiveQuery_instances = new WeakSet(), _LiveQuery_start = async function _LiveQuery_start(generation) {
6935
+ _LiveQuery_client = new WeakMap(), _LiveQuery_uuid = new WeakMap(), _LiveQuery_open = new WeakMap(), _LiveQuery_onResult = new WeakMap(), _LiveQuery_id = new WeakMap(), _LiveQuery_revision = new WeakMap(), _LiveQuery_result = new WeakMap(), _LiveQuery_started = new WeakMap(), _LiveQuery_disposed = new WeakMap(), _LiveQuery_generation = new WeakMap(), _LiveQuery_latest = new WeakMap(), _LiveQuery_buffer = new WeakMap(), _LiveQuery_unlisten = new WeakMap(), _LiveQuery_unreconnect = new WeakMap(), _LiveQuery_opening = new WeakMap(), _LiveQuery_retryTimer = new WeakMap(), _LiveQuery_reopening = new WeakMap(), _LiveQuery_statusListeners = new WeakMap(), _LiveQuery_instances = new WeakSet(), _LiveQuery_start = async function _LiveQuery_start(generation) {
6779
6936
  __classPrivateFieldSet$7(this, _LiveQuery_buffer, [], "f");
6937
+ const opening = new AbortController();
6938
+ __classPrivateFieldSet$7(this, _LiveQuery_opening, opening, "f");
6780
6939
  let subscribed;
6781
6940
  try {
6782
- subscribed = await __classPrivateFieldGet$7(this, _LiveQuery_open, "f").call(this);
6941
+ subscribed = await __classPrivateFieldGet$7(this, _LiveQuery_open, "f").call(this, opening.signal);
6783
6942
  }
6784
6943
  catch (e) {
6785
6944
  if (generation === __classPrivateFieldGet$7(this, _LiveQuery_generation, "f"))
6786
6945
  __classPrivateFieldSet$7(this, _LiveQuery_buffer, null, "f");
6787
6946
  throw e;
6788
6947
  }
6948
+ finally {
6949
+ if (__classPrivateFieldGet$7(this, _LiveQuery_opening, "f") === opening)
6950
+ __classPrivateFieldSet$7(this, _LiveQuery_opening, undefined, "f");
6951
+ }
6789
6952
  if (__classPrivateFieldGet$7(this, _LiveQuery_disposed, "f") || generation !== __classPrivateFieldGet$7(this, _LiveQuery_generation, "f")) {
6790
6953
  __classPrivateFieldGet$7(this, _LiveQuery_client, "f").disposeQuerySubscription(__classPrivateFieldGet$7(this, _LiveQuery_uuid, "f"), subscribed.subscriptionId).catch(() => { });
6791
6954
  // Disposed while opening (e.g. a newer subscribe() on the same
@@ -6795,6 +6958,46 @@ _LiveQuery_client = new WeakMap(), _LiveQuery_uuid = new WeakMap(), _LiveQuery_o
6795
6958
  __classPrivateFieldSet$7(this, _LiveQuery_id, subscribed.subscriptionId, "f");
6796
6959
  __classPrivateFieldGet$7(this, _LiveQuery_instances, "m", _LiveQuery_replace).call(this, subscribed.revision, subscribed.result);
6797
6960
  return __classPrivateFieldGet$7(this, _LiveQuery_result, "f");
6961
+ }, _LiveQuery_reopen = function _LiveQuery_reopen(failures = 0) {
6962
+ if (__classPrivateFieldGet$7(this, _LiveQuery_disposed, "f"))
6963
+ return;
6964
+ const reopened = this.start();
6965
+ const generation = __classPrivateFieldGet$7(this, _LiveQuery_generation, "f");
6966
+ reopened.then(() => {
6967
+ if (__classPrivateFieldGet$7(this, _LiveQuery_disposed, "f") || generation !== __classPrivateFieldGet$7(this, _LiveQuery_generation, "f") || !__classPrivateFieldGet$7(this, _LiveQuery_reopening, "f"))
6968
+ return;
6969
+ __classPrivateFieldSet$7(this, _LiveQuery_reopening, false, "f");
6970
+ __classPrivateFieldGet$7(this, _LiveQuery_instances, "m", _LiveQuery_emit).call(this, { state: 'open' });
6971
+ }, error => {
6972
+ if (__classPrivateFieldGet$7(this, _LiveQuery_disposed, "f") || generation !== __classPrivateFieldGet$7(this, _LiveQuery_generation, "f"))
6973
+ return;
6974
+ const retryInMs = reopenDelay(failures + 1);
6975
+ console.error(`Error re-opening live query (attempt ${failures + 1}), retrying in ${Math.round(retryInMs)}ms:`, error);
6976
+ __classPrivateFieldSet$7(this, _LiveQuery_reopening, true, "f");
6977
+ __classPrivateFieldGet$7(this, _LiveQuery_instances, "m", _LiveQuery_emit).call(this, { state: 'reopening', error, retryInMs });
6978
+ const timer = setTimeout(() => {
6979
+ __classPrivateFieldSet$7(this, _LiveQuery_retryTimer, undefined, "f");
6980
+ __classPrivateFieldGet$7(this, _LiveQuery_instances, "m", _LiveQuery_reopen).call(this, failures + 1);
6981
+ }, retryInMs);
6982
+ // Node: a pending retry must not keep the process alive.
6983
+ if (typeof timer?.unref === 'function')
6984
+ timer.unref();
6985
+ __classPrivateFieldSet$7(this, _LiveQuery_retryTimer, timer, "f");
6986
+ });
6987
+ }, _LiveQuery_clearRetry = function _LiveQuery_clearRetry() {
6988
+ if (__classPrivateFieldGet$7(this, _LiveQuery_retryTimer, "f") === undefined)
6989
+ return;
6990
+ clearTimeout(__classPrivateFieldGet$7(this, _LiveQuery_retryTimer, "f"));
6991
+ __classPrivateFieldSet$7(this, _LiveQuery_retryTimer, undefined, "f");
6992
+ }, _LiveQuery_emit = function _LiveQuery_emit(status) {
6993
+ for (const listener of [...__classPrivateFieldGet$7(this, _LiveQuery_statusListeners, "f")]) {
6994
+ try {
6995
+ listener(status);
6996
+ }
6997
+ catch (e) {
6998
+ console.error('Error in live query status listener:', e);
6999
+ }
7000
+ }
6798
7001
  }, _LiveQuery_replace = function _LiveQuery_replace(revision, result) {
6799
7002
  __classPrivateFieldSet$7(this, _LiveQuery_revision, revision, "f");
6800
7003
  __classPrivateFieldSet$7(this, _LiveQuery_result, result, "f");
@@ -6843,7 +7046,7 @@ _LiveQuery_client = new WeakMap(), _LiveQuery_uuid = new WeakMap(), _LiveQuery_o
6843
7046
  // Replace the subscription with a new one.
6844
7047
  if (!__classPrivateFieldGet$7(this, _LiveQuery_disposed, "f") && generation === __classPrivateFieldGet$7(this, _LiveQuery_generation, "f")) {
6845
7048
  __classPrivateFieldGet$7(this, _LiveQuery_client, "f").disposeQuerySubscription(__classPrivateFieldGet$7(this, _LiveQuery_uuid, "f"), id).catch(() => { });
6846
- this.start().catch(e => console.error('Error re-opening live query:', e));
7049
+ __classPrivateFieldGet$7(this, _LiveQuery_instances, "m", _LiveQuery_reopen).call(this);
6847
7050
  }
6848
7051
  });
6849
7052
  };
@@ -7624,8 +7827,8 @@ class QuerySubscriptionProxy {
7624
7827
  _QuerySubscriptionProxy_initResolve.set(this, void 0);
7625
7828
  _QuerySubscriptionProxy_initReject.set(this, void 0);
7626
7829
  const open = className === undefined
7627
- ? () => client.subscribeQuery(uuid, query)
7628
- : () => client.modelSubscribe(uuid, className, query);
7830
+ ? (signal) => client.subscribeQuery(uuid, query, { signal })
7831
+ : (signal) => client.modelSubscribe(uuid, className, query, { signal });
7629
7832
  __classPrivateFieldSet$6(this, _QuerySubscriptionProxy_live, new LiveQuery(client, uuid, open, result => __classPrivateFieldGet$6(this, _QuerySubscriptionProxy_instances, "m", _QuerySubscriptionProxy_deliver).call(this, result)), "f");
7630
7833
  __classPrivateFieldSet$6(this, _QuerySubscriptionProxy_initialized, new Promise((resolve, reject) => {
7631
7834
  __classPrivateFieldSet$6(this, _QuerySubscriptionProxy_initResolve, resolve, "f");
@@ -7663,9 +7866,23 @@ class QuerySubscriptionProxy {
7663
7866
  __classPrivateFieldGet$6(this, _QuerySubscriptionProxy_callbacks, "f").add(callback);
7664
7867
  return () => __classPrivateFieldGet$6(this, _QuerySubscriptionProxy_callbacks, "f").delete(callback);
7665
7868
  }
7666
- /** End the subscription on the executor and drop all callbacks. */
7667
- dispose() {
7668
- __classPrivateFieldGet$6(this, _QuerySubscriptionProxy_live, "f").dispose();
7869
+ /** Whether the query lost its subscription (a reconnect, a failed
7870
+ * resync), could not open it again yet and is retrying: `result` is then
7871
+ * not live. */
7872
+ get reopening() {
7873
+ return __classPrivateFieldGet$6(this, _QuerySubscriptionProxy_live, "f").reopening;
7874
+ }
7875
+ /** Call `listener` on each failed re-open of the subscription and when a
7876
+ * re-open succeeds after one failed (see {@link LiveQueryStatus}).
7877
+ * Returns a remover. */
7878
+ onStatus(listener) {
7879
+ return __classPrivateFieldGet$6(this, _QuerySubscriptionProxy_live, "f").onStatus(listener);
7880
+ }
7881
+ /** End the subscription on the executor and drop all callbacks. With
7882
+ * `cancelOpening`, a `subscribe()` still waiting on the executor is
7883
+ * cancelled too, and rejects. */
7884
+ dispose(options = {}) {
7885
+ __classPrivateFieldGet$6(this, _QuerySubscriptionProxy_live, "f").dispose(options);
7669
7886
  __classPrivateFieldGet$6(this, _QuerySubscriptionProxy_callbacks, "f").clear();
7670
7887
  }
7671
7888
  }
@@ -8938,16 +9155,11 @@ class PerspectiveProxy {
8938
9155
  async stringOrTemplateObjectToSubjectClassName(subjectClass) {
8939
9156
  if (typeof subjectClass === "string")
8940
9157
  return subjectClass;
8941
- else {
8942
- let subjectClasses = await this.subjectClassesByTemplate(subjectClass);
8943
- if (subjectClasses[0]) {
8944
- return subjectClasses[0];
8945
- }
8946
- else {
8947
- //@ts-ignore
8948
- return subjectClass.className;
8949
- }
8950
- }
9158
+ // The @Model decorator names the class, as in createSubject: no lookup.
9159
+ // Only an undecorated object is matched by its properties.
9160
+ const obj = subjectClass;
9161
+ return obj.className || obj.constructor?.className || obj.constructor?.prototype?.className
9162
+ || (await this.subjectClassesByTemplate(obj))[0];
8951
9163
  }
8952
9164
  /**
8953
9165
  * Creates a new subject instance of the given subject class
@@ -9613,7 +9825,15 @@ class PerspectiveProxy {
9613
9825
  * refuses a Prolog query (400): Prolog live queries are not supported. */
9614
9826
  async subscribeQuery(query) {
9615
9827
  const subscription = new QuerySubscriptionProxy(this.uuid, query, __classPrivateFieldGet$6(this, _PerspectiveProxy_client, "f"));
9616
- await subscription.subscribe();
9828
+ try {
9829
+ await subscription.subscribe();
9830
+ }
9831
+ catch (e) {
9832
+ // Nobody gets the proxy, so nobody can dispose it: left as is, it
9833
+ // would re-open on every reconnect and retry for good (#1595).
9834
+ subscription.dispose({ cancelOpening: true });
9835
+ throw e;
9836
+ }
9617
9837
  return subscription;
9618
9838
  }
9619
9839
  }
@@ -9705,8 +9925,9 @@ class PerspectiveClient {
9705
9925
  return JSON.parse(result);
9706
9926
  }
9707
9927
  /** Open a live SPARQL query. Updates arrive through {@link onQueryUpdate}. */
9708
- async subscribeQuery(uuid, query) {
9709
- return __classPrivateFieldGet$5(this, _PerspectiveClient_apiClient, "f").call('perspective.subscribeQuery', { uuid, query });
9928
+ /** `options.signal` cancels the call, and the executor stops computing the first result. */
9929
+ async subscribeQuery(uuid, query, options) {
9930
+ return __classPrivateFieldGet$5(this, _PerspectiveClient_apiClient, "f").call('perspective.subscribeQuery', { uuid, query }, options);
9710
9931
  }
9711
9932
  /** Every `query-subscription-update` event on this client's socket. */
9712
9933
  onQueryUpdate(cb) {
@@ -9739,8 +9960,9 @@ class PerspectiveClient {
9739
9960
  return JSON.parse(resultJson);
9740
9961
  }
9741
9962
  /** Open a live model query over one class or several. Updates arrive through {@link onQueryUpdate}. */
9742
- async modelSubscribe(uuid, className, queryJson) {
9743
- return __classPrivateFieldGet$5(this, _PerspectiveClient_apiClient, "f").call('perspective.modelSubscribe', { uuid, ...classParams(className), query_json: queryJson });
9963
+ /** `options.signal` cancels the call, and the executor stops computing the first result. */
9964
+ async modelSubscribe(uuid, className, queryJson, options) {
9965
+ return __classPrivateFieldGet$5(this, _PerspectiveClient_apiClient, "f").call('perspective.modelSubscribe', { uuid, ...classParams(className), query_json: queryJson }, options);
9744
9966
  }
9745
9967
  async add(name) {
9746
9968
  const handle = await __classPrivateFieldGet$5(this, _PerspectiveClient_apiClient, "f").call('perspective.create', { name });
@@ -18629,6 +18851,9 @@ function buildSPARQLWhereFilters(metadata, _allRelationsMetadata, where) {
18629
18851
  * Allows building queries with a chainable interface and either
18630
18852
  * running them once or subscribing to real-time updates.
18631
18853
  */
18854
+ /** What a subscription compares to skip a callback whose results equal the
18855
+ * last ones emitted (a resync or a reconnect re-open of an unchanged result). */
18856
+ const fingerprint = (value) => JSON.stringify(value, (_, v) => (typeof v === 'function' ? undefined : v));
18632
18857
  /** Query builder for Ad4mModel queries.
18633
18858
  * Allows building queries with a fluent interface and either running them once
18634
18859
  * or subscribing to updates.
@@ -18683,6 +18908,10 @@ class ModelQueryBuilder {
18683
18908
  }
18684
18909
  return this.ctor.parseModelResult(this.perspective, raw, include, properties);
18685
18910
  }
18911
+ /** Snapshot instances for dirty tracking, as `execute` does for its rows. */
18912
+ takeSnapshots(instances) {
18913
+ this.ctor.takeSnapshots(instances, this.queryParams.include);
18914
+ }
18686
18915
  /** Ends the current subscription, if any, on the client and the executor. */
18687
18916
  dispose() {
18688
18917
  if (this.currentSubscription) {
@@ -19052,7 +19281,6 @@ class ModelQueryBuilder {
19052
19281
  this.dispose();
19053
19282
  const parseResults = (raw) => this.parse(raw);
19054
19283
  // Suppress callbacks whose parsed results equal the last ones emitted.
19055
- const fingerprint = (results) => JSON.stringify(results, (_, v) => (typeof v === 'function' ? undefined : v));
19056
19284
  let lastFingerprint = null;
19057
19285
  const { initial } = await this.live(this.queryParams, (raw) => {
19058
19286
  try {
@@ -19203,73 +19431,46 @@ class ModelQueryBuilder {
19203
19431
  *
19204
19432
  */
19205
19433
  async paginateSubscribe(pageSize, pageNumber, callback) {
19206
- // Clean up any existing subscription
19207
19434
  this.dispose();
19208
- // Subscribe to the full result set (no limit/offset) so the subscription
19209
- // detects changes anywhere in the dataset; each change re-reads the page.
19210
- const subscriptionParams = { ...(this.queryParams || {}) };
19211
- delete subscriptionParams.limit;
19212
- delete subscriptionParams.offset;
19213
- // Build the paginated query for Rust endpoint (count: true fetches both results and totalCount in one call)
19435
+ // Subscribe to the page itself. Since #1237 the executor re-runs a paged
19436
+ // subscription when a record outside the page starts or stops matching
19437
+ // (the `joins` and `scan` trigger rules), and a model result carries
19438
+ // `totalCount`, so a write outside the page still changes the result and
19439
+ // is pushed. Each page is built from the pushed rows: no second query, and
19440
+ // the executor hydrates one page per change rather than every match.
19441
+ // Pushes arrive in revision order, so the last callback is the latest
19442
+ // state (#1051). After dispose() the live query delivers nothing.
19214
19443
  const paginatedQuery = {
19215
19444
  ...(this.queryParams || {}),
19216
19445
  limit: pageSize,
19217
19446
  offset: pageSize * (pageNumber - 1),
19218
19447
  count: true,
19219
19448
  };
19220
- // One read in flight. A dispatch while a read is running sets `pending`
19221
- // so a fetch always completes after the last dispatch. The generation
19222
- // counter from #1020 dropped superseded fetches, but ordered them by
19223
- // start time rather than by how fresh the data they read was — two
19224
- // back-to-back dispatches could keep the fetch that saw 1 model and
19225
- // drop the one that saw 2, after which the server has nothing further
19226
- // to say (issue #1051 / CI: "Paginate callback did not see second model save").
19227
- // After dispose() no read starts and no result is delivered, including
19228
- // a read that was already in flight when dispose() ran.
19229
- let disposed = false;
19230
- let fetching = false;
19231
- let pending = false;
19232
- const processResults = async () => {
19233
- if (disposed)
19234
- return;
19235
- if (fetching) {
19236
- pending = true;
19237
- return;
19238
- }
19239
- fetching = true;
19449
+ // As subscribe(): a callback fires only when the rows or totalCount
19450
+ // differ from the last page emitted, not on a resync or a reconnect
19451
+ // re-open of an unchanged page.
19452
+ let lastFingerprint = null;
19453
+ const toPage = (raw) => {
19454
+ const results = this.parse(raw);
19455
+ const fp = fingerprint([results, raw?.totalCount]);
19456
+ this.takeSnapshots(results);
19457
+ return { page: { results, totalCount: raw?.totalCount, pageSize, pageNumber }, fp };
19458
+ };
19459
+ const { initial } = await this.live(paginatedQuery, (raw) => {
19240
19460
  try {
19241
- const { results, totalCount } = await this.execute(paginatedQuery);
19242
- if (!disposed)
19243
- callback({ results, totalCount, pageSize, pageNumber });
19461
+ const { page, fp } = toPage(raw);
19462
+ if (fp === lastFingerprint)
19463
+ return;
19464
+ lastFingerprint = fp;
19465
+ callback(page);
19244
19466
  }
19245
- finally {
19246
- fetching = false;
19247
- if (pending) {
19248
- pending = false;
19249
- // Detached from the caller's promise: needs its own handler, or a
19250
- // rejection here is unhandled.
19251
- processResults().catch(e => console.error('Paginate subscription error:', e));
19252
- }
19467
+ catch (e) {
19468
+ console.error('Paginate subscription error:', e);
19253
19469
  }
19254
- };
19255
- const { live } = await this.live(subscriptionParams, () => {
19256
- processResults().catch(e => console.error('Paginate subscription error:', e));
19257
19470
  });
19258
- if (this.currentSubscription === live) {
19259
- this.currentSubscription = {
19260
- dispose: () => {
19261
- disposed = true;
19262
- live.dispose();
19263
- },
19264
- };
19265
- }
19266
- else {
19267
- // Disposed, or overtaken by a later subscribe, while opening: deliver nothing.
19268
- disposed = true;
19269
- }
19270
- // Initial fetch (single call with count: true)
19271
- const { results, totalCount } = await this.execute(paginatedQuery);
19272
- return { results, totalCount, pageSize, pageNumber };
19471
+ const { page, fp } = toPage(initial);
19472
+ lastFingerprint = fp;
19473
+ return page;
19273
19474
  }
19274
19475
  /**
19275
19476
  * Subscribes to paginated results updates using SPARQL.
@@ -20431,6 +20632,20 @@ class Ad4mModel {
20431
20632
  return [];
20432
20633
  return arr.map((json) => jsonToModelInstance(this, perspective, json, include, properties));
20433
20634
  }
20635
+ /**
20636
+ * Snapshot freshly built instances for dirty tracking, with the relations
20637
+ * `include` loaded (its `$`-prefixed projection keys are not relations).
20638
+ * Used by every query path, and by ModelQueryBuilder for pushed results.
20639
+ * @internal
20640
+ */
20641
+ static takeSnapshots(instances, include) {
20642
+ const relations = include
20643
+ ? Object.fromEntries(Object.entries(include).filter(([k]) => !k.startsWith('$')))
20644
+ : undefined;
20645
+ const snapshot = relations && Object.keys(relations).length > 0 ? relations : undefined;
20646
+ for (const inst of instances)
20647
+ inst.takeSnapshot?.(snapshot);
20648
+ }
20434
20649
  // ── One query over several classes (#1238) ────────────────────────────────
20435
20650
  /**
20436
20651
  * Build the wire parameters for one query over several classes.
@@ -20532,12 +20747,7 @@ class Ad4mModel {
20532
20747
  const { classNames, queryJson } = Ad4mModel.prepareUnionQueryParams(classes, query);
20533
20748
  const result = await perspective.modelQuery(classNames, queryJson, options);
20534
20749
  const results = Ad4mModel.parseUnionResult(classes, perspective, result, query.include, query.properties);
20535
- const snapshotRelations = query.include
20536
- ? Object.fromEntries(Object.entries(query.include).filter(([k]) => !k.startsWith('$')))
20537
- : undefined;
20538
- for (const inst of results) {
20539
- inst.takeSnapshot?.(snapshotRelations && Object.keys(snapshotRelations).length > 0 ? snapshotRelations : undefined);
20540
- }
20750
+ Ad4mModel.takeSnapshots(results, query.include);
20541
20751
  return { results, totalCount: result.totalCount };
20542
20752
  }
20543
20753
  /**
@@ -20603,13 +20813,7 @@ class Ad4mModel {
20603
20813
  const instances = result.instances.map((json) => {
20604
20814
  return jsonToModelInstance(this, perspective, json, query.include, query.properties);
20605
20815
  });
20606
- // Take snapshots for dirty tracking (exclude $-prefixed projection keys)
20607
- const snapshotRelations = query.include
20608
- ? Object.fromEntries(Object.entries(query.include).filter(([k]) => !k.startsWith('$')))
20609
- : undefined;
20610
- for (const inst of instances) {
20611
- inst.takeSnapshot(snapshotRelations && Object.keys(snapshotRelations).length > 0 ? snapshotRelations : undefined);
20612
- }
20816
+ Ad4mModel.takeSnapshots(instances, query.include);
20613
20817
  return {
20614
20818
  results: instances,
20615
20819
  totalCount: result.totalCount,
@@ -21754,6 +21958,14 @@ class Ad4mClient {
21754
21958
  onAuthFailed(callback) {
21755
21959
  return __classPrivateFieldGet$1(this, _Ad4mClient_apiClient, "f").onAuthFailed(callback);
21756
21960
  }
21961
+ /**
21962
+ * Reconnect now if the connection to the executor dropped and the client is
21963
+ * waiting out its backoff: for a host that knows the executor is back (it
21964
+ * restarted it, or the device woke). A no-op while connected or connecting.
21965
+ */
21966
+ reconnectNow() {
21967
+ __classPrivateFieldGet$1(this, _Ad4mClient_apiClient, "f").reconnectNow();
21968
+ }
21757
21969
  /** Close all event connections and clear in-memory caches */
21758
21970
  close() {
21759
21971
  __classPrivateFieldGet$1(this, _Ad4mClient_agentClient, "f").clearByDidCache();
@@ -23368,6 +23580,17 @@ class WakerSubscriptionManager {
23368
23580
  /** Subscriptions the executor rejected, waiting to be re-attempted. */
23369
23581
  this.pendingSubscriptions = new Map();
23370
23582
  this.retryTimer = null;
23583
+ /** Re-attempt rounds in a row that left something pending, for the backoff. */
23584
+ this.retryRounds = 0;
23585
+ /**
23586
+ * Subscriptions that were active until one of their live queries lost its
23587
+ * executor subscription (a reconnect, a failed resync) and failed to open it
23588
+ * again, with the proxies still re-opening. The query retries on its own,
23589
+ * with backoff, so the manager does not subscribe them again; it reports
23590
+ * them as pending instead of active until every proxy is open again, and
23591
+ * keeps persisting them so a restart restores them (#1595).
23592
+ */
23593
+ this.reopening = new Map();
23371
23594
  /**
23372
23595
  * Cancellation tokens for in-flight `subscribe()` calls.
23373
23596
  *
@@ -23407,6 +23630,7 @@ class WakerSubscriptionManager {
23407
23630
  this.QuerySubscriptionProxyCtor = options.QuerySubscriptionProxy ?? null;
23408
23631
  this.previousSeenMessages = options.previousSeenMessages ?? {};
23409
23632
  this.retryPendingMs = options.retryPendingMs ?? 30000;
23633
+ this.maxRetryPendingMs = Math.max(this.retryPendingMs, options.maxRetryPendingMs ?? 300000);
23410
23634
  this.subscribeTimeoutMs = options.subscribeTimeoutMs ?? 15000;
23411
23635
  this.retryWakeMs = options.retryWakeMs ?? 5000;
23412
23636
  }
@@ -23425,8 +23649,9 @@ class WakerSubscriptionManager {
23425
23649
  * If a subscription with the same id already exists, it is disposed first.
23426
23650
  */
23427
23651
  async subscribe(sub) {
23428
- // Dispose existing subscription with same id if any
23429
- this.dispose(sub.id, false);
23652
+ // Dispose existing subscription with same id if any. Not `dispose()`: a
23653
+ // re-attempt must not start the backoff over.
23654
+ this.release(sub.id, false);
23430
23655
  const token = this.beginAttempt(sub.id);
23431
23656
  if (!this.QuerySubscriptionProxyCtor) {
23432
23657
  throw new Error("WakerSubscriptionManager: QuerySubscriptionProxy must be provided via constructor options");
@@ -23452,10 +23677,13 @@ class WakerSubscriptionManager {
23452
23677
  ? new QuerySubscriptionProxy(sub.perspective, sub.mentionQuery, this.perspectiveClient, sub.mentionClass)
23453
23678
  : undefined;
23454
23679
  const proxies = mentionProxy ? [proxy, mentionProxy] : [proxy];
23680
+ // `cancelOpening`: a handshake given up on must not keep the executor
23681
+ // computing a first result nobody reads; abandoned ones piled up into
23682
+ // hundreds of busy executor threads on staging (#1595).
23455
23683
  const disposeProxies = () => {
23456
23684
  for (const p of proxies) {
23457
23685
  try {
23458
- p.dispose();
23686
+ p.dispose({ cancelOpening: true });
23459
23687
  }
23460
23688
  catch { }
23461
23689
  }
@@ -23507,7 +23735,7 @@ class WakerSubscriptionManager {
23507
23735
  // turn this into an error result instead of a false "Subscribed" reply.
23508
23736
  throw new Error(`Waker subscription ${sub.id} failed: ${msg}${hintFor(msg)}` +
23509
23737
  (this.retryPendingMs > 0
23510
- ? `. Not listening yet — re-attempting every ${Math.round(this.retryPendingMs / 1000)}s; check ad4m_list_waker_subscriptions.`
23738
+ ? `. Not listening yet — re-attempting within ${Math.round(this.retryCeiling() / 1000)}s, then less often (at most every ${Math.round(this.maxRetryPendingMs / 1000)}s); check ad4m_list_waker_subscriptions.`
23511
23739
  : ""));
23512
23740
  }
23513
23741
  if (this.isStale(sub.id, token)) {
@@ -23515,6 +23743,8 @@ class WakerSubscriptionManager {
23515
23743
  return;
23516
23744
  }
23517
23745
  this.pendingSubscriptions.delete(sub.id);
23746
+ if (this.pendingSubscriptions.size === 0)
23747
+ this.retryRounds = 0;
23518
23748
  this.logger.info(`[waker] ${sub.id}: subscription initialized successfully`);
23519
23749
  // Seed from persisted seen messages so we don't re-wake after restart
23520
23750
  const restored = Object.prototype.hasOwnProperty.call(this.previousSeenMessages, sub.id);
@@ -23608,6 +23838,9 @@ class WakerSubscriptionManager {
23608
23838
  };
23609
23839
  proxy.onResult((result) => handleResult(result));
23610
23840
  mentionProxy?.onResult((result) => handleResult(result, false, " (mention query)"));
23841
+ for (const p of proxies) {
23842
+ p.onStatus?.((status) => this.onReopenStatus(sub, proxies, p, status));
23843
+ }
23611
23844
  if (this.isStale(sub.id, token)) {
23612
23845
  disposeProxies();
23613
23846
  return;
@@ -23630,6 +23863,51 @@ class WakerSubscriptionManager {
23630
23863
  this.persist();
23631
23864
  this.logger.info(`[waker] Subscription ${sub.id} active (type=${sub.type}, perspective=${sub.perspective})`);
23632
23865
  }
23866
+ /**
23867
+ * A proxy of `sub` failed to re-open its live query, or re-opened it after
23868
+ * failing. `sub` counts as active again once none of its proxies is still
23869
+ * re-opening. `proxies` tells a status of a replaced subscription apart.
23870
+ */
23871
+ onReopenStatus(sub, proxies, proxy, status) {
23872
+ if (this.proxies.get(sub.id) !== proxies)
23873
+ return;
23874
+ if (status?.state === "reopening") {
23875
+ const entry = this.reopening.get(sub.id) ?? { sub, proxies: new Set() };
23876
+ entry.proxies.add(proxy);
23877
+ if (!this.reopening.has(sub.id)) {
23878
+ this.reopening.set(sub.id, entry);
23879
+ this.activeSubscriptions.delete(sub.id);
23880
+ this.logger.warn(`[waker] ${sub.id}: live query lost after a reconnect and could not be re-opened (${status.error?.message ?? status.error}); not listening, retrying in ${Math.round((status.retryInMs ?? 0) / 1000)}s`);
23881
+ }
23882
+ return;
23883
+ }
23884
+ if (status?.state !== "open")
23885
+ return;
23886
+ const entry = this.reopening.get(sub.id);
23887
+ if (!entry)
23888
+ return;
23889
+ entry.proxies.delete(proxy);
23890
+ if (entry.proxies.size > 0)
23891
+ return;
23892
+ this.reopening.delete(sub.id);
23893
+ this.activeSubscriptions.set(sub.id, sub);
23894
+ this.logger.info(`[waker] ${sub.id}: live query re-opened, listening again`);
23895
+ // Wakes held back while it was not active go out now, not with the next mention.
23896
+ if (this.undelivered.get(sub.id)?.size)
23897
+ this.scheduleMentionWake(sub, proxy.result, this.debounceMs);
23898
+ }
23899
+ /** The wait before the next re-attempt round: `retryPendingMs` doubled per
23900
+ * round in a row that left something pending, capped at
23901
+ * `maxRetryPendingMs`, and between half and all of that, so wakers of a
23902
+ * restarted executor do not all retry at once. */
23903
+ nextRetryDelay() {
23904
+ const ceiling = this.retryCeiling();
23905
+ return ceiling / 2 + Math.random() * (ceiling / 2);
23906
+ }
23907
+ /** The longest the next re-attempt round waits. */
23908
+ retryCeiling() {
23909
+ return Math.min(this.retryPendingMs * 2 ** this.retryRounds, this.maxRetryPendingMs);
23910
+ }
23633
23911
  /** Arm the re-attempt timer if pending subscriptions are waiting. */
23634
23912
  scheduleRetry() {
23635
23913
  if (this.retryPendingMs <= 0)
@@ -23638,8 +23916,9 @@ class WakerSubscriptionManager {
23638
23916
  return;
23639
23917
  this.retryTimer = setTimeout(() => {
23640
23918
  this.retryTimer = null;
23919
+ this.retryRounds++;
23641
23920
  void this.retryPending();
23642
- }, this.retryPendingMs);
23921
+ }, this.nextRetryDelay());
23643
23922
  if (typeof this.retryTimer.unref === "function")
23644
23923
  this.retryTimer.unref();
23645
23924
  }
@@ -23673,26 +23952,39 @@ class WakerSubscriptionManager {
23673
23952
  }
23674
23953
  }
23675
23954
  }
23676
- /** Subscriptions that were rejected and are waiting to be re-attempted. */
23955
+ /** Subscriptions that are not listening and are being re-attempted: the
23956
+ * ones the executor rejected, and active ones whose live query is
23957
+ * re-opening after a reconnect. */
23677
23958
  getPending() {
23678
- return Array.from(this.pendingSubscriptions.values());
23959
+ return [
23960
+ ...this.pendingSubscriptions.values(),
23961
+ ...Array.from(this.reopening.values(), (entry) => entry.sub),
23962
+ ];
23679
23963
  }
23680
23964
  /**
23681
23965
  * Dispose a single subscription.
23682
23966
  * @param persist — if false, skip calling onPersist (used during batch cleanup).
23683
23967
  */
23684
23968
  dispose(id, persist = true) {
23969
+ this.release(id, persist);
23970
+ if (this.pendingSubscriptions.size === 0)
23971
+ this.retryRounds = 0;
23972
+ }
23973
+ /** Drop everything held for `id`, as `dispose()` does, but leave the
23974
+ * re-attempt backoff as it is. */
23975
+ release(id, persist) {
23685
23976
  // Invalidate any subscribe() for this id that is still awaiting.
23686
23977
  this.generations.set(id, (this.generations.get(id) ?? 0) + 1);
23687
23978
  for (const proxy of this.proxies.get(id) ?? []) {
23688
23979
  try {
23689
- proxy.dispose();
23980
+ proxy.dispose({ cancelOpening: true });
23690
23981
  }
23691
23982
  catch {
23692
23983
  /* ignore */
23693
23984
  }
23694
23985
  }
23695
23986
  this.proxies.delete(id);
23987
+ this.reopening.delete(id);
23696
23988
  const timer = this.debounceTimers.get(id);
23697
23989
  if (timer) {
23698
23990
  clearTimeout(timer);
@@ -23765,6 +24057,8 @@ class WakerSubscriptionManager {
23765
24057
  this.dispose(id, false);
23766
24058
  }
23767
24059
  this.pendingSubscriptions.clear();
24060
+ this.reopening.clear();
24061
+ this.retryRounds = 0;
23768
24062
  if (this.retryTimer) {
23769
24063
  clearTimeout(this.retryTimer);
23770
24064
  this.retryTimer = null;
@@ -23824,7 +24118,9 @@ class WakerSubscriptionManager {
23824
24118
  for (const [id, set] of this.delivered) {
23825
24119
  seen[id] = Array.from(set);
23826
24120
  }
23827
- this.onPersist(this.getActive(), seen);
24121
+ // A subscription that is re-opening was enrolled and is coming back: a
24122
+ // restart in the meantime must restore it.
24123
+ this.onPersist([...this.getActive(), ...Array.from(this.reopening.values(), (entry) => entry.sub)], seen);
23828
24124
  }
23829
24125
  }
23830
24126
  }
@@ -24269,4 +24565,4 @@ const SCOPED_EVENTS = new Set([
24269
24565
  "flow-state-changed",
24270
24566
  ]);
24271
24567
 
24272
- export { ACCEPTED_BY_GETTER, AIClient, Model as AIModel, AIModelLoadingStatus, AIPromptExamples, AIPromptExamplesInput, AITask, AITaskInput, Ad4mClient, Ad4mModel, Agent, AgentClient, AgentExpression, AgentSignature, AgentStatus, Apps, AuthInfo, AuthInfoInput, AutoProcessorConfig, BelongsToMany, BelongsToOne, CALL_PROTOCOL_VERSION, Capability, CapabilityInput, ComputeLogEntry, Container, DEFAULT_ICE_SERVERS, EntanglementProof, EntanglementProofInput, ExceptionInfo, ExceptionType, Expression, ExpressionGeneric, ExpressionGenericInput, ExpressionProof, ExpressionProofInput, ExpressionRef, ExpressionRendered, Flag, FlowInstance, FlowInstanceRecord, FlowTransitionProposal, HasMany, HasOne, HostingUserInfo, IDBCache, Icon, ImportResult, ImportStats, InteractionCall, InteractionMeta, InteractionParameter, InterpretationOverlay, InterpretationRun, LONG_METHODS, LONG_TIMEOUT_MS, LanguageExpression, LanguageHandle, LanguageLanguageInput, LanguageMeta, LanguageMetaInput, LanguageMetaInternal, LanguageRef, Link, LinkExpression, LinkExpressionInput, LinkExpressionMutations, LinkExpressionUpdated, LinkInput, LinkMutations, LinkQuery, Literal, LiveQuery, LocalModel, LocalModelInput, MENTION_TEXT_LIMIT, Mentioning, MeshManager, Model$1 as Model, ModelApi, ModelApiInput, ModelInput, ModelQueryBuilder, Neighbourhood, NeighbourhoodExpression, NeighbourhoodProxy, Notification, NotificationInput, NullCache, OnlineAgent, Optional, PROPOSER_GETTER, PaymentRequestResult, Perspective, PerspectiveDiff, PerspectiveDiffExpression, PerspectiveExpression, PerspectiveHandle, PerspectiveInput, PerspectiveProxy, PerspectiveState, PerspectiveUnsignedInput, Property, QuerySubscriptionProxy, READ_METHODS, ReadOnly, Resource, ResourceInput, RpcError, RuntimeInfo, SCOPED_EVENTS, SHACLFlow, SHACLShape, SMART_LITERAL_CONTENT_PREDICATE, SentMessage, SmartLiteral, TextContent, TokenizerSource, TokenizerSourceInput, TriggeredNotification, UserCreationResult, UserStatistics, VerificationRequestResult, VoiceActivityParamsInput, WakerSubscriptionManager, applyUpdate, buildConformanceFilter, buildModelFromJSONSchema, buildPaginationSubquery, buildSDNA, buildSHACL, buildSPARQLQuery, buildWhereCondition, capSentence, clearQueryCache, coalesce, compileWhereClause, concat, createPersistentCache, createTelepresenceChannel, determineNamespace, determinePredicate, effectiveLiteralStorage, escapeQueryString, exists, exprRef2String, fileToDataUri, fn, focus, formatList, formatQueryValue, formatSPARQLValue, getCachedResult, getDefaultValueForType, getMemoizedSHACL, getPropertiesMetadata, getPropertyOption, getRelationsMetadata, hasJsOnlyWhereFilters, hintFor, holdsAWholeWordTerm, ifExpr, invalidatePerspectiveCache, isArrayType, isContainedScope, isContainmentTraversal, isExpression, isIncludeProjection, isLink, isNodeExpression, isNumericType, isObjectType, isSchemaType, isTraverseScope, linkEqual, linkExpressionInputToWire, linkExpressionToWire, linkMutationsToWire, literal, looksLikeUri, mentionOf, neighbourhoodExpressionFromWire, normalizeNamespaceString, normalizeSchemaType, normalizeValue, normalizeWhereForSparql, parseCallMessage, parseExprUrl, parseLit, parseLitBoolean, parseLitNumber, parseSparqlCount, path, queryCacheSize, requireSingleParent, resolveParentPredicate, setCachedResult, setPropertyRegistryEntry, setRelationRegistryEntry, typeDefsString, valueToLiteralIri };
24568
+ export { ACCEPTED_BY_GETTER, AIClient, Model as AIModel, AIModelLoadingStatus, AIPromptExamples, AIPromptExamplesInput, AITask, AITaskInput, Ad4mClient, Ad4mModel, Agent, AgentClient, AgentExpression, AgentSignature, AgentStatus, Apps, AuthInfo, AuthInfoInput, AutoProcessorConfig, BelongsToMany, BelongsToOne, CALL_PROTOCOL_VERSION, Capability, CapabilityInput, ComputeLogEntry, Container, DEFAULT_ICE_SERVERS, EntanglementProof, EntanglementProofInput, ExceptionInfo, ExceptionType, Expression, ExpressionGeneric, ExpressionGenericInput, ExpressionProof, ExpressionProofInput, ExpressionRef, ExpressionRendered, Flag, FlowInstance, FlowInstanceRecord, FlowTransitionProposal, HasMany, HasOne, HostingUserInfo, IDBCache, Icon, ImportResult, ImportStats, InteractionCall, InteractionMeta, InteractionParameter, InterpretationOverlay, InterpretationRun, LONG_METHODS, LONG_TIMEOUT_MS, LanguageExpression, LanguageHandle, LanguageLanguageInput, LanguageMeta, LanguageMetaInput, LanguageMetaInternal, LanguageRef, Link, LinkExpression, LinkExpressionInput, LinkExpressionMutations, LinkExpressionUpdated, LinkInput, LinkMutations, LinkQuery, Literal, LiveQuery, LocalModel, LocalModelInput, MENTION_TEXT_LIMIT, Mentioning, MeshManager, Model$1 as Model, ModelApi, ModelApiInput, ModelInput, ModelQueryBuilder, Neighbourhood, NeighbourhoodExpression, NeighbourhoodProxy, Notification, NotificationInput, NullCache, OnlineAgent, Optional, PROPOSER_GETTER, PaymentRequestResult, Perspective, PerspectiveDiff, PerspectiveDiffExpression, PerspectiveExpression, PerspectiveHandle, PerspectiveInput, PerspectiveProxy, PerspectiveState, PerspectiveUnsignedInput, Property, QuerySubscriptionProxy, READ_METHODS, REOPEN_BASE_DELAY_MS, REOPEN_MAX_DELAY_MS, ReadOnly, Resource, ResourceInput, RpcError, RuntimeInfo, SCOPED_EVENTS, SHACLFlow, SHACLShape, SMART_LITERAL_CONTENT_PREDICATE, SentMessage, SmartLiteral, TextContent, TokenizerSource, TokenizerSourceInput, TriggeredNotification, UserCreationResult, UserStatistics, VerificationRequestResult, VoiceActivityParamsInput, WakerSubscriptionManager, applyUpdate, buildConformanceFilter, buildModelFromJSONSchema, buildPaginationSubquery, buildSDNA, buildSHACL, buildSPARQLQuery, buildWhereCondition, capSentence, clearQueryCache, coalesce, compileWhereClause, concat, createPersistentCache, createTelepresenceChannel, determineNamespace, determinePredicate, effectiveLiteralStorage, escapeQueryString, exists, exprRef2String, fileToDataUri, fn, focus, formatList, formatQueryValue, formatSPARQLValue, getCachedResult, getDefaultValueForType, getMemoizedSHACL, getPropertiesMetadata, getPropertyOption, getRelationsMetadata, hasJsOnlyWhereFilters, hintFor, holdsAWholeWordTerm, ifExpr, invalidatePerspectiveCache, isArrayType, isContainedScope, isContainmentTraversal, isExpression, isIncludeProjection, isLink, isNodeExpression, isNumericType, isObjectType, isSchemaType, isTraverseScope, linkEqual, linkExpressionInputToWire, linkExpressionToWire, linkMutationsToWire, literal, looksLikeUri, mentionOf, neighbourhoodExpressionFromWire, normalizeNamespaceString, normalizeSchemaType, normalizeValue, normalizeWhereForSparql, parseCallMessage, parseExprUrl, parseLit, parseLitBoolean, parseLitNumber, parseSparqlCount, path, queryCacheSize, reopenDelay, requireSingleParent, resolveParentPredicate, setCachedResult, setPropertyRegistryEntry, setRelationRegistryEntry, typeDefsString, valueToLiteralIri };