@arca-network/sdk 2.1.0 → 2.2.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;
@@ -1742,7 +1759,11 @@ class MaxOrderSizeWatchStream extends WatchStream {
1742
1759
  this.askRatio = options.askRatio;
1743
1760
  }
1744
1761
  this.unsubs.push(this.priceStream.onUpdate((prices) => {
1745
- this.prices = { ...prices };
1762
+ // Merge, don't replace: `initialPrices` is a REST `getMarketMids()`
1763
+ // read taken at setup, and it may hold the only mark we have for a
1764
+ // market the live stream has not carried yet. Replacing threw that
1765
+ // away on the first tick of any unrelated market.
1766
+ this.prices = { ...this.prices, ...prices };
1746
1767
  this.recompute('mids');
1747
1768
  }), this.priceStream.onStateChange((state) => {
1748
1769
  if (state === 'reconnecting')
@@ -1904,6 +1925,12 @@ exports.MaxOrderSizeWatchStream = MaxOrderSizeWatchStream;
1904
1925
  * `arca.watchPrices(...)`. Call `.close()` when done. On reconnect the server
1905
1926
  * re-sends a snapshot so `.prices` is never stale on reconnect — only
1906
1927
  * temporarily empty during the initial `ready()` wait.
1928
+ *
1929
+ * Because the subscription is ref-counted, the server only sends a snapshot
1930
+ * once per subscribe — so the manager retains that map and replays it to every
1931
+ * later subscriber. A second `watchPrices()` therefore starts from the same
1932
+ * prices as the first, rather than filling in one market at a time as each one
1933
+ * happens to tick.
1907
1934
  */
1908
1935
  class PriceWatchStream extends WatchStream {
1909
1936
  ws;
@@ -2503,10 +2530,32 @@ function intervalToMs(interval) {
2503
2530
  function hasInlineStructuralExchangeState(exchangeState) {
2504
2531
  return exchangeState?.pendingIntents !== undefined;
2505
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;
2506
2550
  /**
2507
2551
  * Reactive stream of exchange state including positions, orders, and
2508
2552
  * pending intents. Subscribes to `exchange.updated` events for structural
2509
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.
2510
2559
  */
2511
2560
  class ExchangeWatchStream extends WatchStream {
2512
2561
  ws;
@@ -2519,8 +2568,17 @@ class ExchangeWatchStream extends WatchStream {
2519
2568
  latestMids = {};
2520
2569
  unsubs = [];
2521
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;
2522
2578
  observationEpoch = 0;
2523
2579
  expiryTimer;
2580
+ recoveryTimer;
2581
+ recoveryAttempt = 0;
2524
2582
  constructor(ws, objectPath, objectId, fetchState, exchange = 'sim') {
2525
2583
  super();
2526
2584
  this.ws = ws;
@@ -2533,10 +2591,20 @@ class ExchangeWatchStream extends WatchStream {
2533
2591
  if (status === 'disconnected' && this.state !== 'loading') {
2534
2592
  this.setState('reconnecting');
2535
2593
  }
2536
- 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.
2537
2600
  this.refetch();
2538
2601
  }
2539
- }), 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) => {
2540
2608
  if (event.entityId !== this.objectId && event.entityPath !== this.objectPath) {
2541
2609
  return;
2542
2610
  }
@@ -2580,10 +2648,22 @@ class ExchangeWatchStream extends WatchStream {
2580
2648
  get pendingIntents() {
2581
2649
  return this._exchangeState?.pendingIntents ?? [];
2582
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
+ }
2583
2662
  applyStructural(state, event) {
2584
2663
  this.observationEpoch++;
2585
2664
  if (this.expiryTimer)
2586
2665
  clearTimeout(this.expiryTimer);
2666
+ this.clearRecovery();
2587
2667
  const allocation = state.tradingAllocation;
2588
2668
  if (allocation?.validUntil) {
2589
2669
  const deadline = Date.parse(allocation.validUntil);
@@ -2614,11 +2694,45 @@ class ExchangeWatchStream extends WatchStream {
2614
2694
  this.structuralState = undefined;
2615
2695
  this._exchangeState = undefined;
2616
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;
2617
2726
  }
2618
2727
  refetch(triggerEvent) {
2619
- if (this.fetchInFlight || this.isClosed)
2728
+ if (this.isClosed)
2729
+ return;
2730
+ if (this.fetchInFlight) {
2731
+ this.refetchQueued = true;
2620
2732
  return;
2733
+ }
2621
2734
  this.fetchInFlight = true;
2735
+ this.refetchQueued = false;
2622
2736
  const epoch = this.observationEpoch;
2623
2737
  this.fetchState(this.objectId)
2624
2738
  .then((state) => {
@@ -2627,11 +2741,16 @@ class ExchangeWatchStream extends WatchStream {
2627
2741
  this.applyStructural(state, triggerEvent);
2628
2742
  })
2629
2743
  .catch(() => { })
2630
- .finally(() => { this.fetchInFlight = false; });
2744
+ .finally(() => {
2745
+ this.fetchInFlight = false;
2746
+ if (this.refetchQueued && !this.isClosed)
2747
+ this.refetch();
2748
+ });
2631
2749
  }
2632
2750
  doClose() {
2633
2751
  if (this.expiryTimer)
2634
2752
  clearTimeout(this.expiryTimer);
2753
+ this.clearRecovery();
2635
2754
  this.unsubs.forEach(u => u());
2636
2755
  this.ws.unwatchPath(this.objectPath);
2637
2756
  this.ws.releaseMids();