@lifi/perps-sdk 0.0.0-preview-64fca0d

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
+}

package/src/websocket/types.ts

@@ -0,0 +1,75 @@
+import type { Subscription, SubscriptionEvent } from '@lifi/perps-types'
+import type {
+  ProviderGetQuoteParams,
+  QuoteListener,
+} from '../types/provider.js'
+
+/**
+ * The concrete {@link SubscriptionEvent} variant a given subscription `S`
+ * emits, narrowed by its `channel`.
+ *
+ * @public
+ */
+export type EventForSubscription<S extends Subscription> = Extract<
+  SubscriptionEvent,
+  { channel: S['channel'] }
+>
+
+/**
+ * Listener invoked with each realtime {@link SubscriptionEvent}.
+ *
+ * @public
+ */
+export type SubscriptionListener = (event: SubscriptionEvent) => void
+
+/**
+ * Health of a provider's underlying WS connection.
+ *
+ * - `connected` — socket open, live data flowing.
+ * - `reconnecting` — socket dropped; auto-reconnect with backoff in progress.
+ *   Data may be stale until it returns to `connected`.
+ * - `disconnected` — reconnection abandoned after the retry cap. The
+ *   connection is permanently dead and will not recover on its own; the
+ *   subscription's data is stale. Terminal.
+ *
+ * @public
+ */
+export type WsConnectionStatus = 'connected' | 'reconnecting' | 'disconnected'
+
+/**
+ * Listener invoked when the underlying WS connection's health changes.
+ *
+ * @public
+ */
+export type WsStatusListener = (status: WsConnectionStatus) => void
+
+/**
+ * Per-provider realtime transport contract used by {@link PerpsWsClient}.
+ * Implemented by the provider packages' WS plugins.
+ *
+ * @public
+ */
+export interface WsProvider {
+  subscribe(
+    sub: Subscription,
+    listener: SubscriptionListener,
+    onStatus?: WsStatusListener
+  ): Promise<() => void>
+  /**
+   * Recover a terminally exhausted connection. Safe no-op unless status is
+   * `disconnected`.
+   */
+  reconnect(): void
+  /**
+   * Stream live fill {@link Quote}s for `params.size` USD notional of
+   * `params.symbol` on this venue, layered on the orderbook channel: the
+   * provider resolves the symbol against its own markets and re-runs the
+   * one-shot quote transform on each (throttled) book update, applying its
+   * public base fee tier. Returns an idempotent unsubscribe.
+   */
+  subscribeQuote(
+    params: ProviderGetQuoteParams,
+    onQuote: QuoteListener
+  ): Promise<() => void>
+  close(): void
+}

package/src/websocket/wsLog.ts

@@ -0,0 +1,82 @@
+const MAX_PAYLOAD_CHARS = 512
+
+const truncate = (raw: string): string =>
+  raw.length > MAX_PAYLOAD_CHARS
+    ? `${raw.slice(0, MAX_PAYLOAD_CHARS)}…(${raw.length} chars)`
+    : raw
+
+/**
+ * Structured logger for WS message-handling and subscription failures, shared
+ * by the provider packages so a malformed frame, a throwing mapper, or a failed
+ * resubscribe never vanishes silently.
+ *
+ * @internal
+ */
+export const wsLog = {
+  /**
+   * A single frame that could not be parsed as JSON. Expected to recur on a
+   * noisy stream, so logged at `warn` with a truncated payload — never fatal.
+   */
+  parseFailure(provider: string, raw: string): void {
+    console.warn(`[${provider}:ws] dropping unparseable frame`, truncate(raw))
+  },
+  /**
+   * A frame parsed but its handler threw (mapper bug, `MarketNotFound`, …).
+   * This is unexpected and must surface; the frame is skipped so one bad
+   * frame does not stall the stream or starve other channels.
+   */
+  handlerFailure(provider: string, error: unknown): void {
+    console.error(`[${provider}:ws] message handler threw`, error)
+  },
+  /**
+   * An `error`-channel frame the server pushed (e.g. a rejected or duplicate
+   * subscription). The frame parsed fine — this is the venue reporting a
+   * problem, not a malformed frame — so surface it at `error` with the
+   * server's own text rather than mislabelling it a parse failure.
+   */
+  serverError(provider: string, message: string): void {
+    console.error(`[${provider}:ws] server error`, message)
+  },
+  /**
+   * A channel's (re)subscribe threw while (re)opening the socket — e.g. an
+   * auth-token fetch rejected after a reconnect. Surfaced at `error`; the
+   * channel is skipped so one failure does not abort the others.
+   */
+  subscribeFailure(provider: string, channel: string, error: unknown): void {
+    console.error(
+      `[${provider}:ws] resubscribe failed for channel '${channel}'; it will not receive updates until the next reconnect.`,
+      error
+    )
+  },
+  /**
+   * A frame item referenced a market id missing from the registry (e.g.
+   * listed after the snapshot). The item is skipped — never the whole frame —
+   * so logged at `warn`.
+   */
+  unknownMarket(provider: string, marketId: string): void {
+    console.warn(
+      `[${provider}:ws] skipping item for unknown market '${marketId}'`
+    )
+  },
+  /**
+   * A background market-registry refetch rejected. Unknown-market items keep
+   * being skipped until the next cooldown-gated retry, so logged at `warn`.
+   */
+  marketRefreshFailure(provider: string, error: unknown): void {
+    console.warn(`[${provider}:ws] market registry refresh failed`, error)
+  },
+  /**
+   * A consumer listener callback threw during fan-out. Logged and skipped so
+   * one bad listener cannot starve sibling listeners or break socket flow.
+   */
+  listenerFailure(
+    provider: string,
+    listenerType: string,
+    error: unknown
+  ): void {
+    console.error(
+      `[${provider}:ws] listener threw during '${listenerType}' fan-out`,
+      error
+    )
+  },
+} as const