@lifi/perps-sdk 0.2.0-alpha.0 → 1.0.0

package/src/websocket/ReconnectingWebSocket.ts

@@ -0,0 +1,353 @@
+import type {
+  CloseEvent as PartySocketCloseEvent,
+  ErrorEvent as PartySocketErrorEvent,
+} from 'partysocket/ws'
+import PartySocketWebSocket from 'partysocket/ws'
+import type { WsConnectionStatus, WsStatusListener } from './types.js'
+import { wsLog } from './wsLog.js'
+
+type WsEventMap = {
+  open: () => void
+  close: (code: number, reason: string) => void
+  error: (error: Event) => void
+  message: (data: string) => void
+}
+
+type WsEvent = keyof WsEventMap
+
+/**
+ * Default reconnect attempt cap. With the jittered backoff below, ten attempts
+ * span roughly 20–60s of retries before the socket is declared `disconnected`
+ * — long enough for a live trading feed to ride out a transient network blip.
+ */
+const DEFAULT_MAX_RETRIES = 10
+
+/** Default watchdog window: three keepalive intervals without inbound traffic. */
+const DEFAULT_STALE_WINDOW_PING_INTERVALS = 3
+
+const CONNECTION_TIMEOUT_MS = 4_000
+/** Uptime below which an open does not reset the retry budget, so an accept-then-drop server still exhausts. */
+const MIN_UPTIME_MS = 5_000
+const MAX_ENQUEUED_MESSAGES = 1_000
+/** First-retry delay is drawn once per socket from [500, 1500)ms to de-synchronize reconnect storms. */
+const MIN_RECONNECTION_DELAY_MS = 500
+const RECONNECTION_JITTER_MS = 1_000
+const MAX_RECONNECTION_DELAY_MS = 10_000
+
+const CLOSED_ERROR = 'WebSocket closed'
+const EXHAUSTED_ERROR = 'WebSocket max reconnect attempts reached'
+const WS_PROVIDER_KEY = 'reconnecting-websocket'
+
+/**
+ * Options for {@link ReconnectingWebSocket}.
+ *
+ * @public
+ */
+export interface ReconnectingWebSocketOptions {
+  maxRetries?: number
+  pingIntervalMs?: number
+  /**
+   * Keepalive frame sent every `pingIntervalMs` while the socket is open.
+   * Framing is venue-specific, so when omitted no keepalive is sent.
+   */
+  pingPayload?: string
+  /**
+   * Stale-stream watchdog window. With `pingPayload` configured, the socket is
+   * force-reconnected when no inbound frame arrives within this window.
+   * Defaults to 3× `pingIntervalMs`.
+   */
+  staleWindowMs?: number
+}
+
+/**
+ * A `WebSocket` transport that auto-reconnects with jittered exponential
+ * backoff (`partysocket` internals), buffers sends (bounded) while
+ * disconnected, keepalive-pings with the caller-supplied `pingPayload`, and
+ * force-reconnects a silently stale stream. Surfaces the
+ * {@link WsConnectionStatus} state machine: `reconnecting` on transient drops,
+ * terminal `disconnected` once the retry budget is exhausted.
+ *
+ * @public
+ */
+export class ReconnectingWebSocket {
+  private readonly socket: PartySocketWebSocket
+  private readonly maxRetries: number
+  private readonly pingIntervalMs: number
+  private readonly pingPayload: string | undefined
+  private readonly staleWindowMs: number
+  private closed = false
+  private reconnectRequested = false
+  private lastCloseRetryCount: number
+  private pingTimer: ReturnType<typeof setInterval> | null = null
+  private staleTimer: ReturnType<typeof setTimeout> | null = null
+  private listeners = {
+    open: new Set<WsEventMap['open']>(),
+    close: new Set<WsEventMap['close']>(),
+    error: new Set<WsEventMap['error']>(),
+    message: new Set<WsEventMap['message']>(),
+  }
+  private statusListeners = new Set<WsStatusListener>()
+  private status: WsConnectionStatus = 'reconnecting'
+  private readyResolvers: Array<{
+    resolve: () => void
+    reject: (e: Error) => void
+  }> = []
+
+  constructor(url: string, options?: ReconnectingWebSocketOptions) {
+    this.maxRetries = options?.maxRetries ?? DEFAULT_MAX_RETRIES
+    this.pingIntervalMs = options?.pingIntervalMs ?? 30_000
+    this.pingPayload = options?.pingPayload
+    this.staleWindowMs =
+      options?.staleWindowMs ??
+      this.pingIntervalMs * DEFAULT_STALE_WINDOW_PING_INTERVALS
+    this.socket = new PartySocketWebSocket(url, undefined, {
+      maxRetries: this.maxRetries,
+      connectionTimeout: CONNECTION_TIMEOUT_MS,
+      minUptime: MIN_UPTIME_MS,
+      maxEnqueuedMessages: MAX_ENQUEUED_MESSAGES,
+      minReconnectionDelay:
+        MIN_RECONNECTION_DELAY_MS + Math.random() * RECONNECTION_JITTER_MS,
+      maxReconnectionDelay: MAX_RECONNECTION_DELAY_MS,
+    })
+    this.lastCloseRetryCount = this.socket.retryCount
+    // The onX handlers receive the raw events; addEventListener would hand out
+    // partysocket's clones, which rewrite an empty close reason in Node.
+    this.socket.onopen = this.handleOpen
+    this.socket.onclose = this.handleClose
+    this.socket.onerror = this.handleError
+    this.socket.onmessage = this.handleMessage
+  }
+
+  private handleOpen = () => {
+    this.startPing()
+    this.armWatchdog()
+    this.setStatus('connected')
+    for (const fn of this.listeners.open) {
+      this.callListener('open', fn)
+    }
+    for (const { resolve } of this.readyResolvers) {
+      resolve()
+    }
+    this.readyResolvers = []
+  }
+
+  private handleClose = (event: PartySocketCloseEvent) => {
+    this.stopPing()
+    this.clearWatchdog()
+    if (this.closed) {
+      return
+    }
+    for (const fn of this.listeners.close) {
+      this.callListener('close', fn, event.code, event.reason)
+    }
+    // partysocket schedules the next attempt — incrementing retryCount —
+    // before dispatching close, and exhausts silently: a retryCount at the cap
+    // that did not move since the previous close means no attempt was
+    // scheduled, i.e. the retry budget is spent.
+    const retryCount = this.socket.retryCount
+    const exhausted =
+      !this.reconnectRequested &&
+      retryCount >= this.maxRetries &&
+      retryCount === this.lastCloseRetryCount
+    this.lastCloseRetryCount = retryCount
+    if (exhausted) {
+      for (const { reject } of this.readyResolvers) {
+        reject(new Error(EXHAUSTED_ERROR))
+      }
+      this.readyResolvers = []
+      this.setStatus('disconnected')
+    } else {
+      this.setStatus('reconnecting')
+    }
+  }
+
+  private handleError = (event: PartySocketErrorEvent) => {
+    for (const fn of this.listeners.error) {
+      this.callListener('error', fn, event)
+    }
+  }
+
+  private handleMessage = (event: MessageEvent) => {
+    this.armWatchdog()
+    const data =
+      typeof event.data === 'string' ? event.data : String(event.data)
+    for (const fn of this.listeners.message) {
+      this.callListener('message', fn, data)
+    }
+  }
+
+  private setStatus(status: WsConnectionStatus) {
+    if (this.status === status) {
+      return
+    }
+    this.status = status
+    for (const fn of this.statusListeners) {
+      this.callListener('status', fn, status)
+    }
+  }
+
+  private callListener<TArgs extends unknown[]>(
+    listenerType: string,
+    listener: (...args: TArgs) => void,
+    ...args: TArgs
+  ) {
+    try {
+      listener(...args)
+    } catch (error) {
+      wsLog.listenerFailure(WS_PROVIDER_KEY, listenerType, error)
+    }
+  }
+
+  private startPing() {
+    const payload = this.pingPayload
+    if (payload === undefined) {
+      return
+    }
+    this.pingTimer = setInterval(() => {
+      if (this.socket.readyState === PartySocketWebSocket.OPEN) {
+        this.socket.send(payload)
+      }
+    }, this.pingIntervalMs)
+  }
+
+  private stopPing() {
+    if (this.pingTimer) {
+      clearInterval(this.pingTimer)
+      this.pingTimer = null
+    }
+  }
+
+  private armWatchdog() {
+    if (this.pingPayload === undefined || this.closed) {
+      return
+    }
+    this.clearWatchdog()
+    this.staleTimer = setTimeout(() => {
+      // The keepalive went unanswered for the whole window: the connection is
+      // half-open and serving stale data — tear it down and reconnect.
+      this.reconnect()
+    }, this.staleWindowMs)
+  }
+
+  private clearWatchdog() {
+    if (this.staleTimer) {
+      clearTimeout(this.staleTimer)
+      this.staleTimer = null
+    }
+  }
+
+  /**
+   * Send `data`, buffering it (bounded) for replay when the socket is not yet
+   * open.
+   *
+   * @public
+   */
+  send(data: string) {
+    this.socket.send(data)
+  }
+
+  /**
+   * Permanently close the socket and suppress further reconnection.
+   *
+   * @public
+   */
+  close() {
+    this.closed = true
+    this.stopPing()
+    this.clearWatchdog()
+    this.socket.close()
+    for (const { reject } of this.readyResolvers) {
+      reject(new Error(CLOSED_ERROR))
+    }
+    this.readyResolvers = []
+  }
+
+  /**
+   * Drop the current connection (if any) and reconnect with a fresh retry
+   * budget. Recovers a socket that reached terminal `disconnected`: status
+   * returns to `reconnecting` and the normal backoff cycle restarts.
+   *
+   * @public
+   */
+  reconnect() {
+    this.closed = false
+    // Suppress the exhaustion check for the synchronous teardown close the
+    // underlying reconnect dispatches — a fresh attempt is always scheduled.
+    this.reconnectRequested = true
+    this.socket.reconnect()
+    this.reconnectRequested = false
+    this.lastCloseRetryCount = this.socket.retryCount
+    this.setStatus('reconnecting')
+  }
+
+  /**
+   * Register a listener for a socket lifecycle event.
+   *
+   * @public
+   */
+  on<E extends WsEvent>(event: E, fn: WsEventMap[E]) {
+    ;(this.listeners[event] as Set<WsEventMap[E]>).add(fn)
+  }
+
+  /**
+   * Remove a previously registered lifecycle-event listener.
+   *
+   * @public
+   */
+  off<E extends WsEvent>(event: E, fn: WsEventMap[E]) {
+    ;(this.listeners[event] as Set<WsEventMap[E]>).delete(fn)
+  }
+
+  /**
+   * Current connection health. `reconnecting` until the first open;
+   * `disconnected` once auto-reconnect is abandoned (terminal until
+   * {@link ReconnectingWebSocket.reconnect} is called).
+   *
+   * @public
+   */
+  getStatus(): WsConnectionStatus {
+    return this.status
+  }
+
+  /**
+   * Register a connection-health listener. Fires on every status transition,
+   * including the terminal `disconnected` emitted on reconnect exhaustion.
+   *
+   * @public
+   */
+  onStatus(fn: WsStatusListener) {
+    this.statusListeners.add(fn)
+  }
+
+  /**
+   * Remove a previously registered connection-health listener.
+   *
+   * @public
+   */
+  offStatus(fn: WsStatusListener) {
+    this.statusListeners.delete(fn)
+  }
+
+  /**
+   * Resolve once the socket is open; reject if it closes or exhausts retries
+   * before opening. When the socket is already terminally dead — `close()`d or
+   * reconnect-exhausted (`disconnected`) — rejects immediately rather than
+   * queuing a waiter nothing would ever settle.
+   *
+   * @public
+   */
+  ready(): Promise<void> {
+    if (this.socket.readyState === PartySocketWebSocket.OPEN) {
+      return Promise.resolve()
+    }
+    if (this.closed) {
+      return Promise.reject(new Error(CLOSED_ERROR))
+    }
+    if (this.status === 'disconnected') {
+      return Promise.reject(new Error(EXHAUSTED_ERROR))
+    }
+    return new Promise((resolve, reject) => {
+      this.readyResolvers.push({ resolve, reject })
+    })
+  }
+}

package/src/websocket/WsProviderBase.ts

@@ -0,0 +1,333 @@
+import type { Subscription, SubscriptionEvent } from '@lifi/perps-types'
+import type {
+  ProviderGetQuoteParams,
+  QuoteListener,
+} from '../types/provider.js'
+import type { ReconnectingWebSocket } from './ReconnectingWebSocket.js'
+import type {
+  SubscriptionListener,
+  WsProvider,
+  WsStatusListener,
+} from './types.js'
+import { wsLog } from './wsLog.js'
+
+/**
+ * Linger before tearing a channel off the wire after its last listener
+ * releases. A re-subscribe to the same key within this window cancels the
+ * pending teardown, so React StrictMode's synchronous unmount→remount (ref
+ * count 1→0→1) and fast route flips collapse to one wire subscription rather
+ * than a subscribe→unsubscribe→subscribe churn the venue would reject.
+ *
+ * @public
+ */
+export const WS_CHANNEL_TEARDOWN_LINGER_MS = 250
+
+interface ChannelEntry {
+  /**
+   * Per-listener ref count — a `Map`, not a `Set`, because the same listener
+   * reference may subscribe twice (StrictMode) and only the matching number of
+   * releases may drop it; a `Set` would lose it on the first sibling release.
+   */
+  listeners: Map<SubscriptionListener, number>
+  /** Wire teardown from {@link WsProviderBase.openChannel}, set once the open resolves. */
+  teardown?: () => void
+  /** In-flight open, set on the 0→1 transition so concurrent subscribes share it. */
+  opening?: Promise<() => void>
+  /** Deferred-teardown timer, set on the 1→0 transition; cleared if re-subscribed within the linger. */
+  pendingTeardown?: ReturnType<typeof setTimeout>
+}
+
+/**
+ * Base for per-provider realtime transports. Owns the {@link
+ * ReconnectingWebSocket}, the fan-out lifecycle — ref-counted multi-listener
+ * subscription per channel key, deferred teardown, status fan-out — so any
+ * number of consumers (and StrictMode double-mounts) collapse to exactly one
+ * wire subscribe/unsubscribe per key, and the wire-subscription registry:
+ * subs recorded via {@link WsProviderBase.registerSub} are sent only while
+ * connected and replayed (failure-isolated) on every (re)open. Subclasses own
+ * everything wire-specific via {@link WsProviderBase.openChannel}, {@link
+ * WsProviderBase.sendSubscribe} and {@link WsProviderBase.handleMessage}:
+ * payload framing, frame validation and dispatch.
+ *
+ * `TSub` is the per-subscription state {@link WsProviderBase.sendSubscribe}
+ * needs to (re)build one subscribe frame.
+ *
+ * @public
+ */
+export abstract class WsProviderBase<TSub = unknown> implements WsProvider {
+  protected readonly rws: ReconnectingWebSocket
+  protected readonly providerKey: string
+
+  private readonly channels = new Map<string, ChannelEntry>()
+  private readonly statusListeners = new Map<WsStatusListener, number>()
+  private readonly wireSubs = new Map<string, TSub>()
+
+  constructor(rws: ReconnectingWebSocket, providerKey: string) {
+    this.providerKey = providerKey
+    this.rws = rws
+    this.rws.on('message', (data) => this.handleMessage(data))
+    this.rws.on('open', () => {
+      void this.replaySubs()
+    })
+    this.rws.onStatus((status) => {
+      for (const fn of this.statusListeners.keys()) {
+        this.callListener('status', fn, status)
+      }
+    })
+  }
+
+  async subscribe(
+    sub: Subscription,
+    listener: SubscriptionListener,
+    onStatus?: WsStatusListener
+  ): Promise<() => void> {
+    this.reconnect()
+
+    const key = this.toKey(sub)
+    await this.acquireChannel(key, sub, listener)
+
+    if (onStatus) {
+      this.statusListeners.set(
+        onStatus,
+        (this.statusListeners.get(onStatus) ?? 0) + 1
+      )
+      onStatus(this.rws.getStatus())
+    }
+
+    return () => {
+      if (onStatus) {
+        const remaining = (this.statusListeners.get(onStatus) ?? 0) - 1
+        if (remaining > 0) {
+          this.statusListeners.set(onStatus, remaining)
+        } else {
+          this.statusListeners.delete(onStatus)
+        }
+      }
+      this.releaseChannel(key, listener)
+    }
+  }
+
+  reconnect(): void {
+    if (this.rws.getStatus() !== 'disconnected') {
+      return
+    }
+    this.rws.reconnect()
+  }
+
+  close(): void {
+    for (const entry of this.channels.values()) {
+      if (entry.pendingTeardown !== undefined) {
+        clearTimeout(entry.pendingTeardown)
+      }
+    }
+    this.onClose()
+    this.rws.close()
+    this.channels.clear()
+    this.statusListeners.clear()
+    this.wireSubs.clear()
+  }
+
+  /** Deliver an event to every listener on `key`. */
+  protected emit(key: string, event: SubscriptionEvent): void {
+    const entry = this.channels.get(key)
+    if (entry === undefined) {
+      return
+    }
+    for (const fn of entry.listeners.keys()) {
+      this.callListener(`subscription:${key}`, fn, event)
+    }
+  }
+
+  /**
+   * Tear `key` off the wire immediately if no listener holds it — i.e. it is
+   * lingering in the deferred-teardown window (or its open is still
+   * unwinding). Returns `true` when the key is free (absent or just torn
+   * down), `false` — leaving the channel untouched — while live listeners
+   * hold it. Lets a subclass that enforces an exclusivity invariant across
+   * keys reclaim a released channel without waiting out the linger.
+   */
+  protected closeChannelIfIdle(key: string): boolean {
+    const entry = this.channels.get(key)
+    if (entry === undefined) {
+      return true
+    }
+    if (entry.listeners.size > 0) {
+      return false
+    }
+    if (entry.pendingTeardown !== undefined) {
+      clearTimeout(entry.pendingTeardown)
+    }
+    entry.teardown?.()
+    this.channels.delete(key)
+    return true
+  }
+
+  /**
+   * Record a wire subscription for replay-on-(re)open and, when the socket is
+   * already connected, send its subscribe frame via {@link sendSubscribe}.
+   * While the socket is down the replay loop on the next open is the sole
+   * sender — sending in both places would double-subscribe. A failed send
+   * removes the sub again so a rejected open leaves no registry entry behind.
+   */
+  protected async registerSub(key: string, state: TSub): Promise<void> {
+    this.wireSubs.set(key, state)
+    if (this.rws.getStatus() !== 'connected') {
+      return
+    }
+    try {
+      await this.sendSubscribe(state)
+    } catch (err) {
+      this.wireSubs.delete(key)
+      throw err
+    }
+  }
+
+  /** Forget a wire subscription so the next (re)open no longer replays it. */
+  protected unregisterSub(key: string): void {
+    this.wireSubs.delete(key)
+  }
+
+  private async replaySubs(): Promise<void> {
+    for (const [key, state] of this.wireSubs) {
+      // Isolate each resubscribe: a send can reject (e.g. an auth-token fetch
+      // after reconnect), and one sub's failure must not abort the rest of
+      // the loop or escape as an unhandled rejection.
+      try {
+        await this.sendSubscribe(state)
+      } catch (err) {
+        wsLog.subscribeFailure(this.providerKey, key, err)
+      }
+    }
+  }
+
+  /** Venue-specific {@link WsProvider.subscribeQuote}; see `resolveSubscribeQuote`. */
+  abstract subscribeQuote(
+    params: ProviderGetQuoteParams,
+    onQuote: QuoteListener
+  ): Promise<() => void>
+
+  /** Canonical fan-out key for `sub`; must match the key the subclass emits to. */
+  protected abstract toKey(sub: Subscription): string
+
+  /**
+   * Open the channel on the wire (0→1 transition only). Record the wire
+   * sub(s) via {@link registerSub} and return a closure that unregisters them
+   * and sends the unsubscribe frame(s).
+   */
+  protected abstract openChannel(sub: Subscription): Promise<() => void>
+
+  /**
+   * Encode and send the subscribe frame for one registered sub. Called by the
+   * base while connected — once on register and again on every (re)open — so
+   * it must be safe to invoke repeatedly with the same state (e.g. re-fetch a
+   * fresh auth token per call rather than embedding one in `state`).
+   */
+  protected abstract sendSubscribe(state: TSub): void | Promise<void>
+
+  /** Parse one inbound frame and route it via {@link emit}. */
+  protected abstract handleMessage(raw: string): void
+
+  /** Release subclass-only resources on {@link close} (keep-alive, cached state). */
+  protected onClose(): void {}
+
+  private callListener<TArgs extends unknown[]>(
+    listenerType: string,
+    listener: (...args: TArgs) => void,
+    ...args: TArgs
+  ): void {
+    try {
+      listener(...args)
+    } catch (error) {
+      wsLog.listenerFailure(this.providerKey, listenerType, error)
+    }
+  }
+
+  private async acquireChannel(
+    key: string,
+    sub: Subscription,
+    listener: SubscriptionListener
+  ): Promise<void> {
+    let entry = this.channels.get(key)
+    if (entry === undefined) {
+      entry = { listeners: new Map() }
+      this.channels.set(key, entry)
+    }
+
+    // Register first (ref-counted) so a frame arriving during an in-flight open
+    // is delivered; cancel any pending teardown (re-subscribe within the linger).
+    entry.listeners.set(listener, (entry.listeners.get(listener) ?? 0) + 1)
+    if (entry.pendingTeardown !== undefined) {
+      clearTimeout(entry.pendingTeardown)
+      entry.pendingTeardown = undefined
+    }
+
+    if (entry.teardown !== undefined) {
+      return
+    }
+    if (entry.opening !== undefined) {
+      await entry.opening
+      return
+    }
+
+    const opening = this.openChannel(sub)
+    entry.opening = opening
+    try {
+      const teardown = await opening
+      const current = this.channels.get(key)
+      if (current === undefined || current.listeners.size === 0) {
+        // Every listener released while opening — unwind immediately.
+        teardown()
+        this.channels.delete(key)
+        return
+      }
+      current.teardown = teardown
+      current.opening = undefined
+    } catch (err) {
+      // Open failed: drop the channel so all (concurrent) subscribers reject
+      // cleanly and a later subscribe re-opens.
+      this.channels.delete(key)
+      throw err
+    }
+  }
+
+  private releaseChannel(key: string, listener: SubscriptionListener): void {
+    const entry = this.channels.get(key)
+    if (entry === undefined) {
+      return
+    }
+
+    const remaining = (entry.listeners.get(listener) ?? 0) - 1
+    if (remaining > 0) {
+      entry.listeners.set(listener, remaining)
+      return
+    }
+    entry.listeners.delete(listener)
+    if (entry.listeners.size > 0) {
+      return
+    }
+
+    if (entry.teardown === undefined) {
+      // Open not resolved yet — acquireChannel's post-open check unwinds it.
+      if (entry.opening === undefined) {
+        this.channels.delete(key)
+      }
+      return
+    }
+
+    if (entry.pendingTeardown !== undefined) {
+      return
+    }
+    entry.pendingTeardown = setTimeout(() => {
+      const e = this.channels.get(key)
+      if (e === undefined) {
+        return
+      }
+      if (e.listeners.size > 0) {
+        e.pendingTeardown = undefined
+        return
+      }
+      e.teardown?.()
+      this.channels.delete(key)
+    }, WS_CHANNEL_TEARDOWN_LINGER_MS)
+  }
+}

package/src/websocket/cachePromise.ts

@@ -0,0 +1,30 @@
+/**
+ * Single-flight a promise through a caller-owned cache slot, evicting the
+ * cached promise if it rejects so the next call retries cleanly.
+ *
+ * Concurrent callers share the one in-flight promise; the rejection still
+ * propagates to every awaiter that triggered it. Only a settled rejection is
+ * evicted — a resolved promise stays cached.
+ *
+ * @param read - Returns the currently cached promise, or `undefined` if none.
+ * @param write - Stores (or with `undefined`, clears) the cached promise.
+ * @param factory - Creates the promise when the slot is empty.
+ */
+export function cachePromise<T>(
+  read: () => Promise<T> | undefined,
+  write: (promise: Promise<T> | undefined) => void,
+  factory: () => Promise<T>
+): Promise<T> {
+  const cached = read()
+  if (cached) {
+    return cached
+  }
+  const promise = factory()
+  promise.catch(() => {
+    if (read() === promise) {
+      write(undefined)
+    }
+  })
+  write(promise)
+  return promise
+}