@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.cjs CHANGED
@@ -133,6 +133,34 @@ const MAX_RECONNECT_DELAY_MS = 30000;
133
133
  * MAX_WATCH_RETRIES times in a row. */
134
134
  const WATCH_RETRY_DELAY_MS = 1000;
135
135
  const MAX_WATCH_RETRIES = 5;
136
+ /** An open socket sends a ping this often, and must deliver some message
137
+ * (the pong will do) within an interval of the first ping it left
138
+ * unanswered. After a network switch a socket can stay OPEN for minutes with
139
+ * no close event, since no FIN or RST ever arrives; this notices it within
140
+ * two intervals. */
141
+ const PING_INTERVAL_MS = 10000;
142
+ /** The slowest link a socket is given time for. The executor reads a ping
143
+ * only after the frames sent before it, so a ping left unanswered counts as
144
+ * silence only once everything the socket sent before that ping could have
145
+ * crossed this link and PONG_RETURN_MS more have passed, if that takes longer
146
+ * than PING_INTERVAL_MS. Messages that come in meanwhile do not shorten this:
147
+ * they say nothing about how far an upload has got. */
148
+ const SLOWEST_LINK_BYTES_PER_MS = 16; // 16 kB/s
149
+ /** How long a pong gets to come back after its ping could have been read
150
+ * behind a large write. Shorter than PING_INTERVAL_MS, so the few ms a small
151
+ * frame adds before a ping on an idle socket never cost a ping interval. */
152
+ const PONG_RETURN_MS = 5000;
153
+ /** The bytes `text` takes as UTF-8, as a WebSocket text frame sends it. */
154
+ function utf8Length(text) {
155
+ let bytes = text.length;
156
+ for (let i = 0; i < text.length; i++) {
157
+ const unit = text.charCodeAt(i);
158
+ // A surrogate is half of a 4-byte pair: 2 units, 2 extra bytes.
159
+ if (unit >= 0x80)
160
+ bytes += unit < 0x800 || (unit >= 0xd800 && unit <= 0xdfff) ? 1 : 2;
161
+ }
162
+ return bytes;
163
+ }
136
164
  let _idCounter = 0;
137
165
  function nextId() {
138
166
  return String(++_idCounter);
@@ -167,6 +195,14 @@ class ApiClient {
167
195
  this._wsReconnectTimer = null;
168
196
  this._wsReconnectDelay = INITIAL_RECONNECT_DELAY_MS;
169
197
  this._wsPingTimer = null;
198
+ /** When the open socket was first pinged since it last delivered a message; null while none is unanswered. */
199
+ this._wsPingedAt = null;
200
+ /** When that ping could have reached the executor, which reads it only after what the socket sent before it. */
201
+ this._wsPingArrivesBy = 0;
202
+ /** When everything the open socket sent so far could have crossed a SLOWEST_LINK_BYTES_PER_MS link.
203
+ * A message from the socket does not move it back: hearing from the executor says nothing
204
+ * about how much of a large upload has reached it. */
205
+ this._wsSentBy = 0;
170
206
  // The executor sends a socket only the events it asked for (`events.watch`).
171
207
  // What the executor has for the open socket, as sent; a new socket has `{}`.
172
208
  this._watching = '{}';
@@ -176,6 +212,13 @@ class ApiClient {
176
212
  this._watchSent = Promise.resolve();
177
213
  this._watchRetries = 0;
178
214
  this._watchRetryTimer = null;
215
+ this._wakeListening = false;
216
+ /** `online` always; `visibilitychange` only when the page became visible. */
217
+ this._onWake = (event) => {
218
+ if (event.type === 'visibilitychange' && typeof document !== 'undefined' && document.visibilityState !== 'visible')
219
+ return;
220
+ this.reconnectNow();
221
+ };
179
222
  this.baseUrl = baseUrl;
180
223
  this.token = token;
181
224
  this._webSocketImpl = webSocketImpl;
@@ -199,6 +242,9 @@ class ApiClient {
199
242
  return;
200
243
  if (this._authFailed !== null)
201
244
  throw new RpcError(401, this._authFailed);
245
+ // A dial ends any wait for one: a call or subscriber that dials during the backoff
246
+ // leaves no timer behind to swallow the retry after this socket's own drop.
247
+ this._cancelReconnect();
202
248
  const WsImpl = this._webSocketImpl ?? globalThis.WebSocket;
203
249
  const ws = new WsImpl(this._getWsUrl());
204
250
  this._ws = ws;
@@ -223,6 +269,8 @@ class ApiClient {
223
269
  // Only watchApplied() awaits this; a close before open is not an error otherwise.
224
270
  this._wsOpen.catch(() => { });
225
271
  ws.onmessage = (event) => {
272
+ if (this._ws === ws)
273
+ this._wsPingedAt = null;
226
274
  let parsed;
227
275
  try {
228
276
  parsed = JSON.parse(event.data);
@@ -248,7 +296,8 @@ class ApiClient {
248
296
  this._failAuth(rpcError.body);
249
297
  return;
250
298
  }
251
- if (parsed.type === 'pong')
299
+ // A dropped socket's events are not this client's any more: its successor watches again.
300
+ if (parsed.type === 'pong' || this._ws !== ws)
252
301
  return;
253
302
  const perspective = parsed.perspectiveUuid;
254
303
  const regs = this._handlers.get(parsed.type);
@@ -271,14 +320,14 @@ class ApiClient {
271
320
  if (this._ws !== ws)
272
321
  return;
273
322
  this._wsReconnectDelay = INITIAL_RECONNECT_DELAY_MS;
274
- this._startPing();
323
+ this._startPing(ws);
275
324
  // The watch goes out before the queued calls, so the events they cause reach listeners.
276
325
  this._watching = '{}';
277
326
  this._watchRetries = 0;
278
327
  this._flushWatch();
279
328
  for (const pending of this._pendingCalls.values()) {
280
329
  if (!pending.sent) {
281
- ws.send(pending.message);
330
+ this._send(ws, pending.message);
282
331
  pending.sent = true;
283
332
  }
284
333
  }
@@ -329,13 +378,40 @@ class ApiClient {
329
378
  for (const cb of [...this._authFailedCallbacks])
330
379
  callSafely(cb, 'Error in auth-failed callback:', reason);
331
380
  }
332
- _startPing() {
381
+ _startPing(ws) {
333
382
  this._stopPing();
383
+ this._wsPingedAt = null;
384
+ this._wsSentBy = 0;
334
385
  this._wsPingTimer = setInterval(() => {
335
- if (this._ws?.readyState === 1 /* OPEN */) {
336
- this._ws.send(JSON.stringify({ type: 'ping' }));
386
+ if (this._ws !== ws)
387
+ return;
388
+ const ping = JSON.stringify({ type: 'ping' });
389
+ if (this._wsPingedAt === null) {
390
+ this._wsPingedAt = performance.now();
391
+ this._send(ws, ping);
392
+ this._wsPingArrivesBy = this._wsSentBy;
393
+ return;
394
+ }
395
+ if (performance.now() >= Math.max(this._wsPingedAt + PING_INTERVAL_MS, this._wsPingArrivesBy + PONG_RETURN_MS)) {
396
+ this._dropSilentSocket(ws);
397
+ return;
337
398
  }
338
- }, 30000);
399
+ this._send(ws, ping);
400
+ }, PING_INTERVAL_MS);
401
+ }
402
+ /** Send on `ws`, counting how long what the open socket sent could take to cross the slowest link. */
403
+ _send(ws, text) {
404
+ if (this._ws === ws)
405
+ this._wsSentBy = Math.max(this._wsSentBy, performance.now()) + utf8Length(text) / SLOWEST_LINK_BYTES_PER_MS;
406
+ ws.send(text);
407
+ }
408
+ /** The socket answered nothing for a whole ping interval: treat it as
409
+ * closed now. Its close event can take minutes on a dead connection,
410
+ * since the close frame gets no answer either; `_onClose` ignores it then. */
411
+ _dropSilentSocket(ws) {
412
+ console.warn(`WebSocket silent for ${performance.now() - (this._wsPingedAt ?? performance.now())} ms after a ping; reconnecting`);
413
+ this._onClose(ws);
414
+ ws.close();
339
415
  }
340
416
  _stopPing() {
341
417
  if (this._wsPingTimer) {
@@ -350,8 +426,54 @@ class ApiClient {
350
426
  this._wsReconnectDelay = Math.min(this._wsReconnectDelay * 2, MAX_RECONNECT_DELAY_MS);
351
427
  this._wsReconnectTimer = setTimeout(() => {
352
428
  this._wsReconnectTimer = null;
429
+ this._listenForWake(false);
353
430
  this._ensureWs();
354
431
  }, delay);
432
+ this._listenForWake(true);
433
+ }
434
+ /** End the wait for the next dial, if one is pending, without dialling. */
435
+ _cancelReconnect() {
436
+ if (this._wsReconnectTimer) {
437
+ clearTimeout(this._wsReconnectTimer);
438
+ this._wsReconnectTimer = null;
439
+ }
440
+ this._listenForWake(false);
441
+ }
442
+ /**
443
+ * Dial now if the client is waiting out its reconnect backoff (up to 30 s)
444
+ * instead of letting the wait run out. For the moments the host knows the
445
+ * executor may be reachable again: an executor it restarted is up, the
446
+ * device woke. In a browser the client does this itself on `online` and when
447
+ * the page becomes visible. Does nothing while a socket is open or
448
+ * connecting, after `closeAll()` with nothing to reconnect, or once the
449
+ * executor refused the token.
450
+ */
451
+ reconnectNow() {
452
+ if (!this._wsReconnectTimer || this._ws || this._authFailed !== null)
453
+ return;
454
+ this._cancelReconnect();
455
+ // The executor is likely back, so a failure now starts the backoff over.
456
+ this._wsReconnectDelay = INITIAL_RECONNECT_DELAY_MS;
457
+ this._ensureWs();
458
+ }
459
+ /** Listen for `online` and `visibilitychange` exactly while a reconnect
460
+ * timer is pending. Outside a browser (no `window`) it registers nothing. */
461
+ _listenForWake(on) {
462
+ if (on === this._wakeListening)
463
+ return;
464
+ const win = typeof window !== 'undefined' ? window : undefined;
465
+ if (typeof win?.addEventListener !== 'function')
466
+ return;
467
+ const doc = typeof document !== 'undefined' && typeof document.addEventListener === 'function' ? document : undefined;
468
+ this._wakeListening = on;
469
+ if (on) {
470
+ win.addEventListener('online', this._onWake);
471
+ doc?.addEventListener('visibilitychange', this._onWake);
472
+ }
473
+ else {
474
+ win.removeEventListener('online', this._onWake);
475
+ doc?.removeEventListener('visibilitychange', this._onWake);
476
+ }
355
477
  }
356
478
  // ── RPC call method ─────────────────────────────────────────────────────
357
479
  /**
@@ -397,7 +519,7 @@ class ApiClient {
397
519
  }, timeoutMs);
398
520
  const onAbort = () => {
399
521
  if (pending.sent && this._ws?.readyState === 1 /* OPEN */) {
400
- this._ws.send(JSON.stringify({ id: nextId(), type: 'request.cancel', params: { targetId: id } }));
522
+ this._send(this._ws, JSON.stringify({ id: nextId(), type: 'request.cancel', params: { targetId: id } }));
401
523
  }
402
524
  settle(() => reject(new DOMException('Aborted', 'AbortError')));
403
525
  };
@@ -420,7 +542,7 @@ class ApiClient {
420
542
  return;
421
543
  }
422
544
  if (this._ws.readyState === 1 /* OPEN */) {
423
- this._ws.send(message);
545
+ this._send(this._ws, message);
424
546
  pending.sent = true;
425
547
  }
426
548
  });
@@ -541,10 +663,7 @@ class ApiClient {
541
663
  clearTimeout(this._watchRetryTimer);
542
664
  this._watchRetryTimer = null;
543
665
  }
544
- if (this._wsReconnectTimer) {
545
- clearTimeout(this._wsReconnectTimer);
546
- this._wsReconnectTimer = null;
547
- }
666
+ this._cancelReconnect();
548
667
  const ws = this._ws;
549
668
  this._ws = null;
550
669
  this._wsOpen = null;
@@ -6693,7 +6812,19 @@ var __classPrivateFieldGet$7 = (undefined && undefined.__classPrivateFieldGet) |
6693
6812
  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");
6694
6813
  return kind === "m" ? f : kind === "a" ? f.call(receiver) : f ? f.value : state.get(receiver);
6695
6814
  };
6696
- 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;
6815
+ 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;
6816
+ /** Delay before the first retry of a failed re-open; it doubles per failure. */
6817
+ const REOPEN_BASE_DELAY_MS = 1000;
6818
+ /** Longest delay between two re-open attempts. */
6819
+ const REOPEN_MAX_DELAY_MS = 60000;
6820
+ /** The delay before re-open attempt `failures + 1`: between half and all of
6821
+ * `REOPEN_BASE_DELAY_MS * 2^(failures - 1)`, capped at
6822
+ * `REOPEN_MAX_DELAY_MS`. The random half spreads the clients of a restarted
6823
+ * executor apart. */
6824
+ function reopenDelay(failures, random = Math.random) {
6825
+ const ceiling = Math.min(REOPEN_BASE_DELAY_MS * 2 ** Math.max(0, failures - 1), REOPEN_MAX_DELAY_MS);
6826
+ return ceiling / 2 + random() * ceiling / 2;
6827
+ }
6697
6828
  /** Apply one update to the last result. Query rows are a multiset: added rows are appended.
6698
6829
  * Throws when the update names an instance that neither the last result nor
6699
6830
  * the update holds: the last result was wrong, and the caller must resync. */
@@ -6730,10 +6861,14 @@ function applyUpdate(result, update) {
6730
6861
  * One live query on the executor. Holds the last result, applies each update
6731
6862
  * to it, calls `resyncSubscription` when a revision is missing, and opens a
6732
6863
  * new subscription after a reconnect (the executor ends a socket's
6733
- * subscriptions when it closes). `onResult` gets every result after the
6734
- * first; `start()` returns the first.
6864
+ * subscriptions when it closes). A re-open that fails (the executor is
6865
+ * still loading the perspective after a restart) is retried with backoff
6866
+ * until it succeeds or the query is disposed; `onStatus` listeners hear
6867
+ * about it (#1595). `onResult` gets every result after the first; `start()`
6868
+ * returns the first.
6735
6869
  */
6736
6870
  class LiveQuery {
6871
+ /** `open` subscribes on the executor; aborting its signal cancels the call. */
6737
6872
  constructor(client, uuid, open, onResult) {
6738
6873
  _LiveQuery_instances.add(this);
6739
6874
  _LiveQuery_client.set(this, void 0);
@@ -6751,45 +6886,73 @@ class LiveQuery {
6751
6886
  _LiveQuery_buffer.set(this, null);
6752
6887
  _LiveQuery_unlisten.set(this, void 0);
6753
6888
  _LiveQuery_unreconnect.set(this, void 0);
6889
+ // Aborts the subscribe call still in flight, for `dispose({ cancelOpening })`.
6890
+ _LiveQuery_opening.set(this, void 0);
6891
+ _LiveQuery_retryTimer.set(this, void 0);
6892
+ _LiveQuery_reopening.set(this, false);
6893
+ _LiveQuery_statusListeners.set(this, new Set()
6894
+ /** `open` subscribes on the executor; aborting its signal cancels the call. */
6895
+ );
6754
6896
  __classPrivateFieldSet$7(this, _LiveQuery_client, client, "f");
6755
6897
  __classPrivateFieldSet$7(this, _LiveQuery_uuid, uuid, "f");
6756
6898
  __classPrivateFieldSet$7(this, _LiveQuery_open, open, "f");
6757
6899
  __classPrivateFieldSet$7(this, _LiveQuery_onResult, onResult, "f");
6758
6900
  __classPrivateFieldSet$7(this, _LiveQuery_unlisten, client.onQueryUpdate(update => __classPrivateFieldGet$7(this, _LiveQuery_instances, "m", _LiveQuery_receive).call(this, update)), "f");
6759
- __classPrivateFieldSet$7(this, _LiveQuery_unreconnect, client.onReconnect(() => {
6760
- this.start().catch(e => console.error('Error re-opening live query after reconnect:', e));
6761
- }), "f");
6901
+ __classPrivateFieldSet$7(this, _LiveQuery_unreconnect, client.onReconnect(() => __classPrivateFieldGet$7(this, _LiveQuery_instances, "m", _LiveQuery_reopen).call(this)), "f");
6762
6902
  }
6763
6903
  get id() { return __classPrivateFieldGet$7(this, _LiveQuery_id, "f"); }
6764
6904
  get result() { return __classPrivateFieldGet$7(this, _LiveQuery_result, "f"); }
6905
+ /** Whether a re-open failed and the query is waiting to retry it. */
6906
+ get reopening() { return __classPrivateFieldGet$7(this, _LiveQuery_reopening, "f"); }
6907
+ /** Call `listener` on each failed re-open and when a re-open succeeds
6908
+ * after one failed. Returns a remover. */
6909
+ onStatus(listener) {
6910
+ __classPrivateFieldGet$7(this, _LiveQuery_statusListeners, "f").add(listener);
6911
+ return () => __classPrivateFieldGet$7(this, _LiveQuery_statusListeners, "f").delete(listener);
6912
+ }
6765
6913
  /** Open the subscription (again) and return its initial result. A start
6766
6914
  * that a newer one overtakes resolves with the newer one's result. */
6767
6915
  start() {
6768
6916
  var _a;
6917
+ __classPrivateFieldGet$7(this, _LiveQuery_instances, "m", _LiveQuery_clearRetry).call(this);
6769
6918
  __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");
6770
6919
  return __classPrivateFieldGet$7(this, _LiveQuery_latest, "f");
6771
6920
  }
6772
- dispose() {
6921
+ /** End the subscription. With `cancelOpening`, a subscribe call still in
6922
+ * flight is cancelled too, so the executor stops computing a first result
6923
+ * nobody waits for (#1595); the pending `start()` then rejects instead of
6924
+ * resolving with that result. */
6925
+ dispose(options = {}) {
6773
6926
  var _a;
6774
6927
  __classPrivateFieldSet$7(this, _LiveQuery_disposed, true, "f");
6775
6928
  __classPrivateFieldSet$7(this, _LiveQuery_generation, (_a = __classPrivateFieldGet$7(this, _LiveQuery_generation, "f"), _a++, _a), "f");
6929
+ __classPrivateFieldGet$7(this, _LiveQuery_instances, "m", _LiveQuery_clearRetry).call(this);
6930
+ __classPrivateFieldGet$7(this, _LiveQuery_statusListeners, "f").clear();
6776
6931
  __classPrivateFieldGet$7(this, _LiveQuery_unlisten, "f").call(this);
6777
6932
  __classPrivateFieldGet$7(this, _LiveQuery_unreconnect, "f").call(this);
6933
+ if (options.cancelOpening)
6934
+ __classPrivateFieldGet$7(this, _LiveQuery_opening, "f")?.abort();
6778
6935
  if (__classPrivateFieldGet$7(this, _LiveQuery_id, "f"))
6779
6936
  __classPrivateFieldGet$7(this, _LiveQuery_client, "f").disposeQuerySubscription(__classPrivateFieldGet$7(this, _LiveQuery_uuid, "f"), __classPrivateFieldGet$7(this, _LiveQuery_id, "f")).catch(() => { });
6780
6937
  }
6781
6938
  }
6782
- _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) {
6939
+ _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) {
6783
6940
  __classPrivateFieldSet$7(this, _LiveQuery_buffer, [], "f");
6941
+ const opening = new AbortController();
6942
+ __classPrivateFieldSet$7(this, _LiveQuery_opening, opening, "f");
6784
6943
  let subscribed;
6785
6944
  try {
6786
- subscribed = await __classPrivateFieldGet$7(this, _LiveQuery_open, "f").call(this);
6945
+ subscribed = await __classPrivateFieldGet$7(this, _LiveQuery_open, "f").call(this, opening.signal);
6787
6946
  }
6788
6947
  catch (e) {
6789
6948
  if (generation === __classPrivateFieldGet$7(this, _LiveQuery_generation, "f"))
6790
6949
  __classPrivateFieldSet$7(this, _LiveQuery_buffer, null, "f");
6791
6950
  throw e;
6792
6951
  }
6952
+ finally {
6953
+ if (__classPrivateFieldGet$7(this, _LiveQuery_opening, "f") === opening)
6954
+ __classPrivateFieldSet$7(this, _LiveQuery_opening, undefined, "f");
6955
+ }
6793
6956
  if (__classPrivateFieldGet$7(this, _LiveQuery_disposed, "f") || generation !== __classPrivateFieldGet$7(this, _LiveQuery_generation, "f")) {
6794
6957
  __classPrivateFieldGet$7(this, _LiveQuery_client, "f").disposeQuerySubscription(__classPrivateFieldGet$7(this, _LiveQuery_uuid, "f"), subscribed.subscriptionId).catch(() => { });
6795
6958
  // Disposed while opening (e.g. a newer subscribe() on the same
@@ -6799,6 +6962,46 @@ _LiveQuery_client = new WeakMap(), _LiveQuery_uuid = new WeakMap(), _LiveQuery_o
6799
6962
  __classPrivateFieldSet$7(this, _LiveQuery_id, subscribed.subscriptionId, "f");
6800
6963
  __classPrivateFieldGet$7(this, _LiveQuery_instances, "m", _LiveQuery_replace).call(this, subscribed.revision, subscribed.result);
6801
6964
  return __classPrivateFieldGet$7(this, _LiveQuery_result, "f");
6965
+ }, _LiveQuery_reopen = function _LiveQuery_reopen(failures = 0) {
6966
+ if (__classPrivateFieldGet$7(this, _LiveQuery_disposed, "f"))
6967
+ return;
6968
+ const reopened = this.start();
6969
+ const generation = __classPrivateFieldGet$7(this, _LiveQuery_generation, "f");
6970
+ reopened.then(() => {
6971
+ if (__classPrivateFieldGet$7(this, _LiveQuery_disposed, "f") || generation !== __classPrivateFieldGet$7(this, _LiveQuery_generation, "f") || !__classPrivateFieldGet$7(this, _LiveQuery_reopening, "f"))
6972
+ return;
6973
+ __classPrivateFieldSet$7(this, _LiveQuery_reopening, false, "f");
6974
+ __classPrivateFieldGet$7(this, _LiveQuery_instances, "m", _LiveQuery_emit).call(this, { state: 'open' });
6975
+ }, error => {
6976
+ if (__classPrivateFieldGet$7(this, _LiveQuery_disposed, "f") || generation !== __classPrivateFieldGet$7(this, _LiveQuery_generation, "f"))
6977
+ return;
6978
+ const retryInMs = reopenDelay(failures + 1);
6979
+ console.error(`Error re-opening live query (attempt ${failures + 1}), retrying in ${Math.round(retryInMs)}ms:`, error);
6980
+ __classPrivateFieldSet$7(this, _LiveQuery_reopening, true, "f");
6981
+ __classPrivateFieldGet$7(this, _LiveQuery_instances, "m", _LiveQuery_emit).call(this, { state: 'reopening', error, retryInMs });
6982
+ const timer = setTimeout(() => {
6983
+ __classPrivateFieldSet$7(this, _LiveQuery_retryTimer, undefined, "f");
6984
+ __classPrivateFieldGet$7(this, _LiveQuery_instances, "m", _LiveQuery_reopen).call(this, failures + 1);
6985
+ }, retryInMs);
6986
+ // Node: a pending retry must not keep the process alive.
6987
+ if (typeof timer?.unref === 'function')
6988
+ timer.unref();
6989
+ __classPrivateFieldSet$7(this, _LiveQuery_retryTimer, timer, "f");
6990
+ });
6991
+ }, _LiveQuery_clearRetry = function _LiveQuery_clearRetry() {
6992
+ if (__classPrivateFieldGet$7(this, _LiveQuery_retryTimer, "f") === undefined)
6993
+ return;
6994
+ clearTimeout(__classPrivateFieldGet$7(this, _LiveQuery_retryTimer, "f"));
6995
+ __classPrivateFieldSet$7(this, _LiveQuery_retryTimer, undefined, "f");
6996
+ }, _LiveQuery_emit = function _LiveQuery_emit(status) {
6997
+ for (const listener of [...__classPrivateFieldGet$7(this, _LiveQuery_statusListeners, "f")]) {
6998
+ try {
6999
+ listener(status);
7000
+ }
7001
+ catch (e) {
7002
+ console.error('Error in live query status listener:', e);
7003
+ }
7004
+ }
6802
7005
  }, _LiveQuery_replace = function _LiveQuery_replace(revision, result) {
6803
7006
  __classPrivateFieldSet$7(this, _LiveQuery_revision, revision, "f");
6804
7007
  __classPrivateFieldSet$7(this, _LiveQuery_result, result, "f");
@@ -6847,7 +7050,7 @@ _LiveQuery_client = new WeakMap(), _LiveQuery_uuid = new WeakMap(), _LiveQuery_o
6847
7050
  // Replace the subscription with a new one.
6848
7051
  if (!__classPrivateFieldGet$7(this, _LiveQuery_disposed, "f") && generation === __classPrivateFieldGet$7(this, _LiveQuery_generation, "f")) {
6849
7052
  __classPrivateFieldGet$7(this, _LiveQuery_client, "f").disposeQuerySubscription(__classPrivateFieldGet$7(this, _LiveQuery_uuid, "f"), id).catch(() => { });
6850
- this.start().catch(e => console.error('Error re-opening live query:', e));
7053
+ __classPrivateFieldGet$7(this, _LiveQuery_instances, "m", _LiveQuery_reopen).call(this);
6851
7054
  }
6852
7055
  });
6853
7056
  };
@@ -7628,8 +7831,8 @@ class QuerySubscriptionProxy {
7628
7831
  _QuerySubscriptionProxy_initResolve.set(this, void 0);
7629
7832
  _QuerySubscriptionProxy_initReject.set(this, void 0);
7630
7833
  const open = className === undefined
7631
- ? () => client.subscribeQuery(uuid, query)
7632
- : () => client.modelSubscribe(uuid, className, query);
7834
+ ? (signal) => client.subscribeQuery(uuid, query, { signal })
7835
+ : (signal) => client.modelSubscribe(uuid, className, query, { signal });
7633
7836
  __classPrivateFieldSet$6(this, _QuerySubscriptionProxy_live, new LiveQuery(client, uuid, open, result => __classPrivateFieldGet$6(this, _QuerySubscriptionProxy_instances, "m", _QuerySubscriptionProxy_deliver).call(this, result)), "f");
7634
7837
  __classPrivateFieldSet$6(this, _QuerySubscriptionProxy_initialized, new Promise((resolve, reject) => {
7635
7838
  __classPrivateFieldSet$6(this, _QuerySubscriptionProxy_initResolve, resolve, "f");
@@ -7667,9 +7870,23 @@ class QuerySubscriptionProxy {
7667
7870
  __classPrivateFieldGet$6(this, _QuerySubscriptionProxy_callbacks, "f").add(callback);
7668
7871
  return () => __classPrivateFieldGet$6(this, _QuerySubscriptionProxy_callbacks, "f").delete(callback);
7669
7872
  }
7670
- /** End the subscription on the executor and drop all callbacks. */
7671
- dispose() {
7672
- __classPrivateFieldGet$6(this, _QuerySubscriptionProxy_live, "f").dispose();
7873
+ /** Whether the query lost its subscription (a reconnect, a failed
7874
+ * resync), could not open it again yet and is retrying: `result` is then
7875
+ * not live. */
7876
+ get reopening() {
7877
+ return __classPrivateFieldGet$6(this, _QuerySubscriptionProxy_live, "f").reopening;
7878
+ }
7879
+ /** Call `listener` on each failed re-open of the subscription and when a
7880
+ * re-open succeeds after one failed (see {@link LiveQueryStatus}).
7881
+ * Returns a remover. */
7882
+ onStatus(listener) {
7883
+ return __classPrivateFieldGet$6(this, _QuerySubscriptionProxy_live, "f").onStatus(listener);
7884
+ }
7885
+ /** End the subscription on the executor and drop all callbacks. With
7886
+ * `cancelOpening`, a `subscribe()` still waiting on the executor is
7887
+ * cancelled too, and rejects. */
7888
+ dispose(options = {}) {
7889
+ __classPrivateFieldGet$6(this, _QuerySubscriptionProxy_live, "f").dispose(options);
7673
7890
  __classPrivateFieldGet$6(this, _QuerySubscriptionProxy_callbacks, "f").clear();
7674
7891
  }
7675
7892
  }
@@ -8942,16 +9159,11 @@ class PerspectiveProxy {
8942
9159
  async stringOrTemplateObjectToSubjectClassName(subjectClass) {
8943
9160
  if (typeof subjectClass === "string")
8944
9161
  return subjectClass;
8945
- else {
8946
- let subjectClasses = await this.subjectClassesByTemplate(subjectClass);
8947
- if (subjectClasses[0]) {
8948
- return subjectClasses[0];
8949
- }
8950
- else {
8951
- //@ts-ignore
8952
- return subjectClass.className;
8953
- }
8954
- }
9162
+ // The @Model decorator names the class, as in createSubject: no lookup.
9163
+ // Only an undecorated object is matched by its properties.
9164
+ const obj = subjectClass;
9165
+ return obj.className || obj.constructor?.className || obj.constructor?.prototype?.className
9166
+ || (await this.subjectClassesByTemplate(obj))[0];
8955
9167
  }
8956
9168
  /**
8957
9169
  * Creates a new subject instance of the given subject class
@@ -9617,7 +9829,15 @@ class PerspectiveProxy {
9617
9829
  * refuses a Prolog query (400): Prolog live queries are not supported. */
9618
9830
  async subscribeQuery(query) {
9619
9831
  const subscription = new QuerySubscriptionProxy(this.uuid, query, __classPrivateFieldGet$6(this, _PerspectiveProxy_client, "f"));
9620
- await subscription.subscribe();
9832
+ try {
9833
+ await subscription.subscribe();
9834
+ }
9835
+ catch (e) {
9836
+ // Nobody gets the proxy, so nobody can dispose it: left as is, it
9837
+ // would re-open on every reconnect and retry for good (#1595).
9838
+ subscription.dispose({ cancelOpening: true });
9839
+ throw e;
9840
+ }
9621
9841
  return subscription;
9622
9842
  }
9623
9843
  }
@@ -9709,8 +9929,9 @@ class PerspectiveClient {
9709
9929
  return JSON.parse(result);
9710
9930
  }
9711
9931
  /** Open a live SPARQL query. Updates arrive through {@link onQueryUpdate}. */
9712
- async subscribeQuery(uuid, query) {
9713
- return __classPrivateFieldGet$5(this, _PerspectiveClient_apiClient, "f").call('perspective.subscribeQuery', { uuid, query });
9932
+ /** `options.signal` cancels the call, and the executor stops computing the first result. */
9933
+ async subscribeQuery(uuid, query, options) {
9934
+ return __classPrivateFieldGet$5(this, _PerspectiveClient_apiClient, "f").call('perspective.subscribeQuery', { uuid, query }, options);
9714
9935
  }
9715
9936
  /** Every `query-subscription-update` event on this client's socket. */
9716
9937
  onQueryUpdate(cb) {
@@ -9743,8 +9964,9 @@ class PerspectiveClient {
9743
9964
  return JSON.parse(resultJson);
9744
9965
  }
9745
9966
  /** Open a live model query over one class or several. Updates arrive through {@link onQueryUpdate}. */
9746
- async modelSubscribe(uuid, className, queryJson) {
9747
- return __classPrivateFieldGet$5(this, _PerspectiveClient_apiClient, "f").call('perspective.modelSubscribe', { uuid, ...classParams(className), query_json: queryJson });
9967
+ /** `options.signal` cancels the call, and the executor stops computing the first result. */
9968
+ async modelSubscribe(uuid, className, queryJson, options) {
9969
+ return __classPrivateFieldGet$5(this, _PerspectiveClient_apiClient, "f").call('perspective.modelSubscribe', { uuid, ...classParams(className), query_json: queryJson }, options);
9748
9970
  }
9749
9971
  async add(name) {
9750
9972
  const handle = await __classPrivateFieldGet$5(this, _PerspectiveClient_apiClient, "f").call('perspective.create', { name });
@@ -18633,6 +18855,9 @@ function buildSPARQLWhereFilters(metadata, _allRelationsMetadata, where) {
18633
18855
  * Allows building queries with a chainable interface and either
18634
18856
  * running them once or subscribing to real-time updates.
18635
18857
  */
18858
+ /** What a subscription compares to skip a callback whose results equal the
18859
+ * last ones emitted (a resync or a reconnect re-open of an unchanged result). */
18860
+ const fingerprint = (value) => JSON.stringify(value, (_, v) => (typeof v === 'function' ? undefined : v));
18636
18861
  /** Query builder for Ad4mModel queries.
18637
18862
  * Allows building queries with a fluent interface and either running them once
18638
18863
  * or subscribing to updates.
@@ -18687,6 +18912,10 @@ class ModelQueryBuilder {
18687
18912
  }
18688
18913
  return this.ctor.parseModelResult(this.perspective, raw, include, properties);
18689
18914
  }
18915
+ /** Snapshot instances for dirty tracking, as `execute` does for its rows. */
18916
+ takeSnapshots(instances) {
18917
+ this.ctor.takeSnapshots(instances, this.queryParams.include);
18918
+ }
18690
18919
  /** Ends the current subscription, if any, on the client and the executor. */
18691
18920
  dispose() {
18692
18921
  if (this.currentSubscription) {
@@ -19056,7 +19285,6 @@ class ModelQueryBuilder {
19056
19285
  this.dispose();
19057
19286
  const parseResults = (raw) => this.parse(raw);
19058
19287
  // Suppress callbacks whose parsed results equal the last ones emitted.
19059
- const fingerprint = (results) => JSON.stringify(results, (_, v) => (typeof v === 'function' ? undefined : v));
19060
19288
  let lastFingerprint = null;
19061
19289
  const { initial } = await this.live(this.queryParams, (raw) => {
19062
19290
  try {
@@ -19207,73 +19435,46 @@ class ModelQueryBuilder {
19207
19435
  *
19208
19436
  */
19209
19437
  async paginateSubscribe(pageSize, pageNumber, callback) {
19210
- // Clean up any existing subscription
19211
19438
  this.dispose();
19212
- // Subscribe to the full result set (no limit/offset) so the subscription
19213
- // detects changes anywhere in the dataset; each change re-reads the page.
19214
- const subscriptionParams = { ...(this.queryParams || {}) };
19215
- delete subscriptionParams.limit;
19216
- delete subscriptionParams.offset;
19217
- // Build the paginated query for Rust endpoint (count: true fetches both results and totalCount in one call)
19439
+ // Subscribe to the page itself. Since #1237 the executor re-runs a paged
19440
+ // subscription when a record outside the page starts or stops matching
19441
+ // (the `joins` and `scan` trigger rules), and a model result carries
19442
+ // `totalCount`, so a write outside the page still changes the result and
19443
+ // is pushed. Each page is built from the pushed rows: no second query, and
19444
+ // the executor hydrates one page per change rather than every match.
19445
+ // Pushes arrive in revision order, so the last callback is the latest
19446
+ // state (#1051). After dispose() the live query delivers nothing.
19218
19447
  const paginatedQuery = {
19219
19448
  ...(this.queryParams || {}),
19220
19449
  limit: pageSize,
19221
19450
  offset: pageSize * (pageNumber - 1),
19222
19451
  count: true,
19223
19452
  };
19224
- // One read in flight. A dispatch while a read is running sets `pending`
19225
- // so a fetch always completes after the last dispatch. The generation
19226
- // counter from #1020 dropped superseded fetches, but ordered them by
19227
- // start time rather than by how fresh the data they read was — two
19228
- // back-to-back dispatches could keep the fetch that saw 1 model and
19229
- // drop the one that saw 2, after which the server has nothing further
19230
- // to say (issue #1051 / CI: "Paginate callback did not see second model save").
19231
- // After dispose() no read starts and no result is delivered, including
19232
- // a read that was already in flight when dispose() ran.
19233
- let disposed = false;
19234
- let fetching = false;
19235
- let pending = false;
19236
- const processResults = async () => {
19237
- if (disposed)
19238
- return;
19239
- if (fetching) {
19240
- pending = true;
19241
- return;
19242
- }
19243
- fetching = true;
19453
+ // As subscribe(): a callback fires only when the rows or totalCount
19454
+ // differ from the last page emitted, not on a resync or a reconnect
19455
+ // re-open of an unchanged page.
19456
+ let lastFingerprint = null;
19457
+ const toPage = (raw) => {
19458
+ const results = this.parse(raw);
19459
+ const fp = fingerprint([results, raw?.totalCount]);
19460
+ this.takeSnapshots(results);
19461
+ return { page: { results, totalCount: raw?.totalCount, pageSize, pageNumber }, fp };
19462
+ };
19463
+ const { initial } = await this.live(paginatedQuery, (raw) => {
19244
19464
  try {
19245
- const { results, totalCount } = await this.execute(paginatedQuery);
19246
- if (!disposed)
19247
- callback({ results, totalCount, pageSize, pageNumber });
19465
+ const { page, fp } = toPage(raw);
19466
+ if (fp === lastFingerprint)
19467
+ return;
19468
+ lastFingerprint = fp;
19469
+ callback(page);
19248
19470
  }
19249
- finally {
19250
- fetching = false;
19251
- if (pending) {
19252
- pending = false;
19253
- // Detached from the caller's promise: needs its own handler, or a
19254
- // rejection here is unhandled.
19255
- processResults().catch(e => console.error('Paginate subscription error:', e));
19256
- }
19471
+ catch (e) {
19472
+ console.error('Paginate subscription error:', e);
19257
19473
  }
19258
- };
19259
- const { live } = await this.live(subscriptionParams, () => {
19260
- processResults().catch(e => console.error('Paginate subscription error:', e));
19261
19474
  });
19262
- if (this.currentSubscription === live) {
19263
- this.currentSubscription = {
19264
- dispose: () => {
19265
- disposed = true;
19266
- live.dispose();
19267
- },
19268
- };
19269
- }
19270
- else {
19271
- // Disposed, or overtaken by a later subscribe, while opening: deliver nothing.
19272
- disposed = true;
19273
- }
19274
- // Initial fetch (single call with count: true)
19275
- const { results, totalCount } = await this.execute(paginatedQuery);
19276
- return { results, totalCount, pageSize, pageNumber };
19475
+ const { page, fp } = toPage(initial);
19476
+ lastFingerprint = fp;
19477
+ return page;
19277
19478
  }
19278
19479
  /**
19279
19480
  * Subscribes to paginated results updates using SPARQL.
@@ -20435,6 +20636,20 @@ class Ad4mModel {
20435
20636
  return [];
20436
20637
  return arr.map((json) => jsonToModelInstance(this, perspective, json, include, properties));
20437
20638
  }
20639
+ /**
20640
+ * Snapshot freshly built instances for dirty tracking, with the relations
20641
+ * `include` loaded (its `$`-prefixed projection keys are not relations).
20642
+ * Used by every query path, and by ModelQueryBuilder for pushed results.
20643
+ * @internal
20644
+ */
20645
+ static takeSnapshots(instances, include) {
20646
+ const relations = include
20647
+ ? Object.fromEntries(Object.entries(include).filter(([k]) => !k.startsWith('$')))
20648
+ : undefined;
20649
+ const snapshot = relations && Object.keys(relations).length > 0 ? relations : undefined;
20650
+ for (const inst of instances)
20651
+ inst.takeSnapshot?.(snapshot);
20652
+ }
20438
20653
  // ── One query over several classes (#1238) ────────────────────────────────
20439
20654
  /**
20440
20655
  * Build the wire parameters for one query over several classes.
@@ -20536,12 +20751,7 @@ class Ad4mModel {
20536
20751
  const { classNames, queryJson } = Ad4mModel.prepareUnionQueryParams(classes, query);
20537
20752
  const result = await perspective.modelQuery(classNames, queryJson, options);
20538
20753
  const results = Ad4mModel.parseUnionResult(classes, perspective, result, query.include, query.properties);
20539
- const snapshotRelations = query.include
20540
- ? Object.fromEntries(Object.entries(query.include).filter(([k]) => !k.startsWith('$')))
20541
- : undefined;
20542
- for (const inst of results) {
20543
- inst.takeSnapshot?.(snapshotRelations && Object.keys(snapshotRelations).length > 0 ? snapshotRelations : undefined);
20544
- }
20754
+ Ad4mModel.takeSnapshots(results, query.include);
20545
20755
  return { results, totalCount: result.totalCount };
20546
20756
  }
20547
20757
  /**
@@ -20607,13 +20817,7 @@ class Ad4mModel {
20607
20817
  const instances = result.instances.map((json) => {
20608
20818
  return jsonToModelInstance(this, perspective, json, query.include, query.properties);
20609
20819
  });
20610
- // Take snapshots for dirty tracking (exclude $-prefixed projection keys)
20611
- const snapshotRelations = query.include
20612
- ? Object.fromEntries(Object.entries(query.include).filter(([k]) => !k.startsWith('$')))
20613
- : undefined;
20614
- for (const inst of instances) {
20615
- inst.takeSnapshot(snapshotRelations && Object.keys(snapshotRelations).length > 0 ? snapshotRelations : undefined);
20616
- }
20820
+ Ad4mModel.takeSnapshots(instances, query.include);
20617
20821
  return {
20618
20822
  results: instances,
20619
20823
  totalCount: result.totalCount,
@@ -21758,6 +21962,14 @@ class Ad4mClient {
21758
21962
  onAuthFailed(callback) {
21759
21963
  return __classPrivateFieldGet$1(this, _Ad4mClient_apiClient, "f").onAuthFailed(callback);
21760
21964
  }
21965
+ /**
21966
+ * Reconnect now if the connection to the executor dropped and the client is
21967
+ * waiting out its backoff: for a host that knows the executor is back (it
21968
+ * restarted it, or the device woke). A no-op while connected or connecting.
21969
+ */
21970
+ reconnectNow() {
21971
+ __classPrivateFieldGet$1(this, _Ad4mClient_apiClient, "f").reconnectNow();
21972
+ }
21761
21973
  /** Close all event connections and clear in-memory caches */
21762
21974
  close() {
21763
21975
  __classPrivateFieldGet$1(this, _Ad4mClient_agentClient, "f").clearByDidCache();
@@ -23372,6 +23584,17 @@ class WakerSubscriptionManager {
23372
23584
  /** Subscriptions the executor rejected, waiting to be re-attempted. */
23373
23585
  this.pendingSubscriptions = new Map();
23374
23586
  this.retryTimer = null;
23587
+ /** Re-attempt rounds in a row that left something pending, for the backoff. */
23588
+ this.retryRounds = 0;
23589
+ /**
23590
+ * Subscriptions that were active until one of their live queries lost its
23591
+ * executor subscription (a reconnect, a failed resync) and failed to open it
23592
+ * again, with the proxies still re-opening. The query retries on its own,
23593
+ * with backoff, so the manager does not subscribe them again; it reports
23594
+ * them as pending instead of active until every proxy is open again, and
23595
+ * keeps persisting them so a restart restores them (#1595).
23596
+ */
23597
+ this.reopening = new Map();
23375
23598
  /**
23376
23599
  * Cancellation tokens for in-flight `subscribe()` calls.
23377
23600
  *
@@ -23411,6 +23634,7 @@ class WakerSubscriptionManager {
23411
23634
  this.QuerySubscriptionProxyCtor = options.QuerySubscriptionProxy ?? null;
23412
23635
  this.previousSeenMessages = options.previousSeenMessages ?? {};
23413
23636
  this.retryPendingMs = options.retryPendingMs ?? 30000;
23637
+ this.maxRetryPendingMs = Math.max(this.retryPendingMs, options.maxRetryPendingMs ?? 300000);
23414
23638
  this.subscribeTimeoutMs = options.subscribeTimeoutMs ?? 15000;
23415
23639
  this.retryWakeMs = options.retryWakeMs ?? 5000;
23416
23640
  }
@@ -23429,8 +23653,9 @@ class WakerSubscriptionManager {
23429
23653
  * If a subscription with the same id already exists, it is disposed first.
23430
23654
  */
23431
23655
  async subscribe(sub) {
23432
- // Dispose existing subscription with same id if any
23433
- this.dispose(sub.id, false);
23656
+ // Dispose existing subscription with same id if any. Not `dispose()`: a
23657
+ // re-attempt must not start the backoff over.
23658
+ this.release(sub.id, false);
23434
23659
  const token = this.beginAttempt(sub.id);
23435
23660
  if (!this.QuerySubscriptionProxyCtor) {
23436
23661
  throw new Error("WakerSubscriptionManager: QuerySubscriptionProxy must be provided via constructor options");
@@ -23456,10 +23681,13 @@ class WakerSubscriptionManager {
23456
23681
  ? new QuerySubscriptionProxy(sub.perspective, sub.mentionQuery, this.perspectiveClient, sub.mentionClass)
23457
23682
  : undefined;
23458
23683
  const proxies = mentionProxy ? [proxy, mentionProxy] : [proxy];
23684
+ // `cancelOpening`: a handshake given up on must not keep the executor
23685
+ // computing a first result nobody reads; abandoned ones piled up into
23686
+ // hundreds of busy executor threads on staging (#1595).
23459
23687
  const disposeProxies = () => {
23460
23688
  for (const p of proxies) {
23461
23689
  try {
23462
- p.dispose();
23690
+ p.dispose({ cancelOpening: true });
23463
23691
  }
23464
23692
  catch { }
23465
23693
  }
@@ -23511,7 +23739,7 @@ class WakerSubscriptionManager {
23511
23739
  // turn this into an error result instead of a false "Subscribed" reply.
23512
23740
  throw new Error(`Waker subscription ${sub.id} failed: ${msg}${hintFor(msg)}` +
23513
23741
  (this.retryPendingMs > 0
23514
- ? `. Not listening yet — re-attempting every ${Math.round(this.retryPendingMs / 1000)}s; check ad4m_list_waker_subscriptions.`
23742
+ ? `. 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.`
23515
23743
  : ""));
23516
23744
  }
23517
23745
  if (this.isStale(sub.id, token)) {
@@ -23519,6 +23747,8 @@ class WakerSubscriptionManager {
23519
23747
  return;
23520
23748
  }
23521
23749
  this.pendingSubscriptions.delete(sub.id);
23750
+ if (this.pendingSubscriptions.size === 0)
23751
+ this.retryRounds = 0;
23522
23752
  this.logger.info(`[waker] ${sub.id}: subscription initialized successfully`);
23523
23753
  // Seed from persisted seen messages so we don't re-wake after restart
23524
23754
  const restored = Object.prototype.hasOwnProperty.call(this.previousSeenMessages, sub.id);
@@ -23612,6 +23842,9 @@ class WakerSubscriptionManager {
23612
23842
  };
23613
23843
  proxy.onResult((result) => handleResult(result));
23614
23844
  mentionProxy?.onResult((result) => handleResult(result, false, " (mention query)"));
23845
+ for (const p of proxies) {
23846
+ p.onStatus?.((status) => this.onReopenStatus(sub, proxies, p, status));
23847
+ }
23615
23848
  if (this.isStale(sub.id, token)) {
23616
23849
  disposeProxies();
23617
23850
  return;
@@ -23634,6 +23867,51 @@ class WakerSubscriptionManager {
23634
23867
  this.persist();
23635
23868
  this.logger.info(`[waker] Subscription ${sub.id} active (type=${sub.type}, perspective=${sub.perspective})`);
23636
23869
  }
23870
+ /**
23871
+ * A proxy of `sub` failed to re-open its live query, or re-opened it after
23872
+ * failing. `sub` counts as active again once none of its proxies is still
23873
+ * re-opening. `proxies` tells a status of a replaced subscription apart.
23874
+ */
23875
+ onReopenStatus(sub, proxies, proxy, status) {
23876
+ if (this.proxies.get(sub.id) !== proxies)
23877
+ return;
23878
+ if (status?.state === "reopening") {
23879
+ const entry = this.reopening.get(sub.id) ?? { sub, proxies: new Set() };
23880
+ entry.proxies.add(proxy);
23881
+ if (!this.reopening.has(sub.id)) {
23882
+ this.reopening.set(sub.id, entry);
23883
+ this.activeSubscriptions.delete(sub.id);
23884
+ 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`);
23885
+ }
23886
+ return;
23887
+ }
23888
+ if (status?.state !== "open")
23889
+ return;
23890
+ const entry = this.reopening.get(sub.id);
23891
+ if (!entry)
23892
+ return;
23893
+ entry.proxies.delete(proxy);
23894
+ if (entry.proxies.size > 0)
23895
+ return;
23896
+ this.reopening.delete(sub.id);
23897
+ this.activeSubscriptions.set(sub.id, sub);
23898
+ this.logger.info(`[waker] ${sub.id}: live query re-opened, listening again`);
23899
+ // Wakes held back while it was not active go out now, not with the next mention.
23900
+ if (this.undelivered.get(sub.id)?.size)
23901
+ this.scheduleMentionWake(sub, proxy.result, this.debounceMs);
23902
+ }
23903
+ /** The wait before the next re-attempt round: `retryPendingMs` doubled per
23904
+ * round in a row that left something pending, capped at
23905
+ * `maxRetryPendingMs`, and between half and all of that, so wakers of a
23906
+ * restarted executor do not all retry at once. */
23907
+ nextRetryDelay() {
23908
+ const ceiling = this.retryCeiling();
23909
+ return ceiling / 2 + Math.random() * (ceiling / 2);
23910
+ }
23911
+ /** The longest the next re-attempt round waits. */
23912
+ retryCeiling() {
23913
+ return Math.min(this.retryPendingMs * 2 ** this.retryRounds, this.maxRetryPendingMs);
23914
+ }
23637
23915
  /** Arm the re-attempt timer if pending subscriptions are waiting. */
23638
23916
  scheduleRetry() {
23639
23917
  if (this.retryPendingMs <= 0)
@@ -23642,8 +23920,9 @@ class WakerSubscriptionManager {
23642
23920
  return;
23643
23921
  this.retryTimer = setTimeout(() => {
23644
23922
  this.retryTimer = null;
23923
+ this.retryRounds++;
23645
23924
  void this.retryPending();
23646
- }, this.retryPendingMs);
23925
+ }, this.nextRetryDelay());
23647
23926
  if (typeof this.retryTimer.unref === "function")
23648
23927
  this.retryTimer.unref();
23649
23928
  }
@@ -23677,26 +23956,39 @@ class WakerSubscriptionManager {
23677
23956
  }
23678
23957
  }
23679
23958
  }
23680
- /** Subscriptions that were rejected and are waiting to be re-attempted. */
23959
+ /** Subscriptions that are not listening and are being re-attempted: the
23960
+ * ones the executor rejected, and active ones whose live query is
23961
+ * re-opening after a reconnect. */
23681
23962
  getPending() {
23682
- return Array.from(this.pendingSubscriptions.values());
23963
+ return [
23964
+ ...this.pendingSubscriptions.values(),
23965
+ ...Array.from(this.reopening.values(), (entry) => entry.sub),
23966
+ ];
23683
23967
  }
23684
23968
  /**
23685
23969
  * Dispose a single subscription.
23686
23970
  * @param persist — if false, skip calling onPersist (used during batch cleanup).
23687
23971
  */
23688
23972
  dispose(id, persist = true) {
23973
+ this.release(id, persist);
23974
+ if (this.pendingSubscriptions.size === 0)
23975
+ this.retryRounds = 0;
23976
+ }
23977
+ /** Drop everything held for `id`, as `dispose()` does, but leave the
23978
+ * re-attempt backoff as it is. */
23979
+ release(id, persist) {
23689
23980
  // Invalidate any subscribe() for this id that is still awaiting.
23690
23981
  this.generations.set(id, (this.generations.get(id) ?? 0) + 1);
23691
23982
  for (const proxy of this.proxies.get(id) ?? []) {
23692
23983
  try {
23693
- proxy.dispose();
23984
+ proxy.dispose({ cancelOpening: true });
23694
23985
  }
23695
23986
  catch {
23696
23987
  /* ignore */
23697
23988
  }
23698
23989
  }
23699
23990
  this.proxies.delete(id);
23991
+ this.reopening.delete(id);
23700
23992
  const timer = this.debounceTimers.get(id);
23701
23993
  if (timer) {
23702
23994
  clearTimeout(timer);
@@ -23769,6 +24061,8 @@ class WakerSubscriptionManager {
23769
24061
  this.dispose(id, false);
23770
24062
  }
23771
24063
  this.pendingSubscriptions.clear();
24064
+ this.reopening.clear();
24065
+ this.retryRounds = 0;
23772
24066
  if (this.retryTimer) {
23773
24067
  clearTimeout(this.retryTimer);
23774
24068
  this.retryTimer = null;
@@ -23828,7 +24122,9 @@ class WakerSubscriptionManager {
23828
24122
  for (const [id, set] of this.delivered) {
23829
24123
  seen[id] = Array.from(set);
23830
24124
  }
23831
- this.onPersist(this.getActive(), seen);
24125
+ // A subscription that is re-opening was enrolled and is coming back: a
24126
+ // restart in the meantime must restore it.
24127
+ this.onPersist([...this.getActive(), ...Array.from(this.reopening.values(), (entry) => entry.sub)], seen);
23832
24128
  }
23833
24129
  }
23834
24130
  }
@@ -24370,6 +24666,8 @@ exports.PerspectiveUnsignedInput = PerspectiveUnsignedInput;
24370
24666
  exports.Property = Property;
24371
24667
  exports.QuerySubscriptionProxy = QuerySubscriptionProxy;
24372
24668
  exports.READ_METHODS = READ_METHODS;
24669
+ exports.REOPEN_BASE_DELAY_MS = REOPEN_BASE_DELAY_MS;
24670
+ exports.REOPEN_MAX_DELAY_MS = REOPEN_MAX_DELAY_MS;
24373
24671
  exports.ReadOnly = ReadOnly;
24374
24672
  exports.Resource = Resource;
24375
24673
  exports.ResourceInput = ResourceInput;
@@ -24458,6 +24756,7 @@ exports.parseLitNumber = parseLitNumber;
24458
24756
  exports.parseSparqlCount = parseSparqlCount;
24459
24757
  exports.path = path;
24460
24758
  exports.queryCacheSize = queryCacheSize;
24759
+ exports.reopenDelay = reopenDelay;
24461
24760
  exports.requireSingleParent = requireSingleParent;
24462
24761
  exports.resolveParentPredicate = resolveParentPredicate;
24463
24762
  exports.setCachedResult = setCachedResult;