@arca-network/sdk 2.1.1 → 2.3.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/dist/streams.js CHANGED
@@ -31,6 +31,7 @@ exports.WatchStreamReadyTimeoutError = WatchStreamReadyTimeoutError;
31
31
  class WatchStream {
32
32
  updateCallbacks = new Set();
33
33
  stateCallbacks = new Set();
34
+ closeCallbacks = new Set();
34
35
  _state = 'loading';
35
36
  closed = false;
36
37
  readyResolve;
@@ -89,6 +90,19 @@ class WatchStream {
89
90
  this.stateCallbacks.add(cb);
90
91
  return () => { this.stateCallbacks.delete(cb); };
91
92
  }
93
+ /**
94
+ * Register a callback that fires once when the stream is closed.
95
+ * Returns an unsubscribe function. Used by the owning client to drop
96
+ * its bookkeeping for the stream; fires after the subscription is released.
97
+ */
98
+ onClose(cb) {
99
+ if (this.closed) {
100
+ cb();
101
+ return () => { };
102
+ }
103
+ this.closeCallbacks.add(cb);
104
+ return () => { this.closeCallbacks.delete(cb); };
105
+ }
92
106
  /**
93
107
  * Stop listening and release the underlying subscription.
94
108
  */
@@ -99,6 +113,9 @@ class WatchStream {
99
113
  this.updateCallbacks.clear();
100
114
  this.stateCallbacks.clear();
101
115
  this.doClose();
116
+ const closeCallbacks = [...this.closeCallbacks];
117
+ this.closeCallbacks.clear();
118
+ closeCallbacks.forEach(cb => cb());
102
119
  }
103
120
  get isClosed() {
104
121
  return this.closed;
@@ -2513,10 +2530,32 @@ function intervalToMs(interval) {
2513
2530
  function hasInlineStructuralExchangeState(exchangeState) {
2514
2531
  return exchangeState?.pendingIntents !== undefined;
2515
2532
  }
2533
+ /**
2534
+ * Backoff schedule for re-reading an invalidated exchange observation.
2535
+ *
2536
+ * An observation is invalidated by an `exchangeStateUnavailable` push or by
2537
+ * its own `validUntil` deadline passing with no newer push. The designed
2538
+ * recovery is the next coherent push, and the first retry is deliberately
2539
+ * not immediate — an unavailable projection re-read at once would hammer a
2540
+ * mirror that just said it cannot answer. But a push is not guaranteed to
2541
+ * arrive: `exchange.updated` has no durable log, and the server drops an
2542
+ * enrichment that exceeds its budget without assigning a `deliverySeq`, so
2543
+ * neither the gap detector nor a resync marker can see that loss. Without a
2544
+ * bounded fallback read the stream would sit on `reconnecting` with no
2545
+ * state for as long as the relay is quiet. Doubles from 1s to a 30s ceiling
2546
+ * (±20% jitter) and stops the moment any structural state is applied.
2547
+ */
2548
+ const EXCHANGE_RECOVERY_INITIAL_MS = 1_000;
2549
+ const EXCHANGE_RECOVERY_MAX_MS = 30_000;
2516
2550
  /**
2517
2551
  * Reactive stream of exchange state including positions, orders, and
2518
2552
  * pending intents. Subscribes to `exchange.updated` events for structural
2519
2553
  * changes, and to `mids.updated` for real-time client-side P&L revaluation.
2554
+ *
2555
+ * Loss handling: a `deliverySeq` gap or server resync marker, a reconnect,
2556
+ * and an invalidated observation (`exchangeStateUnavailable` / expired
2557
+ * `validUntil`) each trigger a bounded REST re-read guarded by the
2558
+ * observation epoch, so an older read can never overwrite a newer push.
2520
2559
  */
2521
2560
  class ExchangeWatchStream extends WatchStream {
2522
2561
  ws;
@@ -2529,8 +2568,17 @@ class ExchangeWatchStream extends WatchStream {
2529
2568
  latestMids = {};
2530
2569
  unsubs = [];
2531
2570
  fetchInFlight = false;
2571
+ /**
2572
+ * A refetch requested while one was already in flight. The in-flight
2573
+ * read belongs to an older epoch and will be discarded when it lands, so
2574
+ * without this flag two back-to-back bare `exchange.updated` events left
2575
+ * the stream on the state from before BOTH of them until a third arrived.
2576
+ */
2577
+ refetchQueued = false;
2532
2578
  observationEpoch = 0;
2533
2579
  expiryTimer;
2580
+ recoveryTimer;
2581
+ recoveryAttempt = 0;
2534
2582
  constructor(ws, objectPath, objectId, fetchState, exchange = 'sim') {
2535
2583
  super();
2536
2584
  this.ws = ws;
@@ -2543,10 +2591,20 @@ class ExchangeWatchStream extends WatchStream {
2543
2591
  if (status === 'disconnected' && this.state !== 'loading') {
2544
2592
  this.setState('reconnecting');
2545
2593
  }
2546
- else if (status === 'connected' && this._exchangeState) {
2594
+ else if (status === 'connected' && this.state !== 'loading') {
2595
+ // Unconditional once the initial load is done: everything pushed
2596
+ // during the outage is gone, whether or not we held a state when
2597
+ // it started. The previous `&& this._exchangeState` guard skipped
2598
+ // this exact re-read after an invalidation, leaving the stream
2599
+ // empty until the next push.
2547
2600
  this.refetch();
2548
2601
  }
2549
- }), this.ws.onExchangeNotification((event) => {
2602
+ }),
2603
+ // A hole in the server-assigned deliverySeq, or a server resync marker,
2604
+ // means at least one frame for this connection was lost. There is no
2605
+ // durable log to replay `exchange.updated` from, so the recovery is a
2606
+ // fresh read. Every other watch stream does this; this one did not.
2607
+ this.ws.onGap(() => { this.refetch(); }), this.ws.onExchangeNotification((event) => {
2550
2608
  if (event.entityId !== this.objectId && event.entityPath !== this.objectPath) {
2551
2609
  return;
2552
2610
  }
@@ -2590,10 +2648,22 @@ class ExchangeWatchStream extends WatchStream {
2590
2648
  get pendingIntents() {
2591
2649
  return this._exchangeState?.pendingIntents ?? [];
2592
2650
  }
2651
+ /**
2652
+ * Re-read the exchange state now, guarded by the observation epoch.
2653
+ *
2654
+ * For callers that learned out of band that the account changed — e.g.
2655
+ * {@link OrderHandle.accounted} resolving through a REST read after the
2656
+ * account push for that commit was lost. Coalesces with any in-flight
2657
+ * read; a push that lands first wins and the read's result is discarded.
2658
+ */
2659
+ refresh() {
2660
+ this.refetch();
2661
+ }
2593
2662
  applyStructural(state, event) {
2594
2663
  this.observationEpoch++;
2595
2664
  if (this.expiryTimer)
2596
2665
  clearTimeout(this.expiryTimer);
2666
+ this.clearRecovery();
2597
2667
  const allocation = state.tradingAllocation;
2598
2668
  if (allocation?.validUntil) {
2599
2669
  const deadline = Date.parse(allocation.validUntil);
@@ -2624,11 +2694,45 @@ class ExchangeWatchStream extends WatchStream {
2624
2694
  this.structuralState = undefined;
2625
2695
  this._exchangeState = undefined;
2626
2696
  this.setState('reconnecting');
2697
+ this.scheduleRecovery();
2698
+ }
2699
+ /**
2700
+ * Arm the next fallback read of an invalidated observation. Re-armed after
2701
+ * each attempt (whether the read failed or returned nothing usable) and
2702
+ * cancelled by {@link applyStructural} the moment a state is restored, so
2703
+ * it only ever runs while the stream is empty.
2704
+ */
2705
+ scheduleRecovery() {
2706
+ if (this.isClosed)
2707
+ return;
2708
+ if (this.recoveryTimer)
2709
+ clearTimeout(this.recoveryTimer);
2710
+ const base = Math.min(EXCHANGE_RECOVERY_MAX_MS, EXCHANGE_RECOVERY_INITIAL_MS * 2 ** this.recoveryAttempt);
2711
+ const jitter = base * 0.2 * (Math.random() * 2 - 1);
2712
+ this.recoveryAttempt = Math.min(this.recoveryAttempt + 1, 10);
2713
+ this.recoveryTimer = setTimeout(() => {
2714
+ this.recoveryTimer = undefined;
2715
+ if (this.isClosed || this.structuralState)
2716
+ return;
2717
+ this.refetch();
2718
+ this.scheduleRecovery();
2719
+ }, Math.max(0, Math.round(base + jitter)));
2720
+ }
2721
+ clearRecovery() {
2722
+ if (this.recoveryTimer)
2723
+ clearTimeout(this.recoveryTimer);
2724
+ this.recoveryTimer = undefined;
2725
+ this.recoveryAttempt = 0;
2627
2726
  }
2628
2727
  refetch(triggerEvent) {
2629
- if (this.fetchInFlight || this.isClosed)
2728
+ if (this.isClosed)
2729
+ return;
2730
+ if (this.fetchInFlight) {
2731
+ this.refetchQueued = true;
2630
2732
  return;
2733
+ }
2631
2734
  this.fetchInFlight = true;
2735
+ this.refetchQueued = false;
2632
2736
  const epoch = this.observationEpoch;
2633
2737
  this.fetchState(this.objectId)
2634
2738
  .then((state) => {
@@ -2637,11 +2741,16 @@ class ExchangeWatchStream extends WatchStream {
2637
2741
  this.applyStructural(state, triggerEvent);
2638
2742
  })
2639
2743
  .catch(() => { })
2640
- .finally(() => { this.fetchInFlight = false; });
2744
+ .finally(() => {
2745
+ this.fetchInFlight = false;
2746
+ if (this.refetchQueued && !this.isClosed)
2747
+ this.refetch();
2748
+ });
2641
2749
  }
2642
2750
  doClose() {
2643
2751
  if (this.expiryTimer)
2644
2752
  clearTimeout(this.expiryTimer);
2753
+ this.clearRecovery();
2645
2754
  this.unsubs.forEach(u => u());
2646
2755
  this.ws.unwatchPath(this.objectPath);
2647
2756
  this.ws.releaseMids();