@geeqdev/geeq-sdk 0.1.0 → 0.2.0

package/src/socket/geeq-socket.ts

@@ -0,0 +1,827 @@
+import { MAX_UINT32, assertDuration } from '../assert'
+import { originOf } from '../chain/select'
+import { resolveAccountId } from '../crypto/account-id'
+import type { AccountRef } from '../crypto/account-id'
+import { fromBase64, toBase64 } from '../encoding/base64'
+import {
+  GeeqError,
+  invalidArgument,
+  invalidKey,
+  socketClosed,
+  socketUnreachable,
+} from '../errors'
+import { socketRoute } from '../net/routes'
+import {
+  WEBSOCKET_OPEN,
+  assertSocketSchemeReachable,
+  defaultWebSocketFactory,
+  opaqueSocketFailureMessage,
+} from '../net/websocket'
+import type { GeeqWebSocketFactory, GeeqWebSocketLike } from '../net/websocket'
+import { GeeqTrackedTx, reportListenerError } from './tracked-tx'
+import { parseTxStatus } from './tx-status'
+import type { GeeqTxStatusEvent } from './tx-status'
+
+const DEFAULT_OPEN_TIMEOUT_MS = 15_000
+/** The edge proxy drops a socket idle for 60 s; the production wallet pings every 25. */
+const DEFAULT_HEARTBEAT_MS = 25_000
+const DEFAULT_RECONNECT_DELAY_MS = 1_000
+const DEFAULT_MAX_RECONNECT_DELAY_MS = 30_000
+/**
+ * A transaction targets a block no more than ten behind the chain's head, so after about
+ * ten block intervals it has either been decided or never will be. Five minutes covers
+ * that at the ~20 s interval with room for a slow block.
+ */
+const DEFAULT_TRACK_TIMEOUT_MS = 5 * 60_000
+/** Long enough for the next commit to carry a restarted node's buffer forward. */
+const DEFAULT_NONSANE_GRACE_MS = 30_000
+const KEY_BYTES = 32
+
+/**
+ * - `connecting` — the first handshake, inside {@link GeeqSocket.connect}.
+ * - `open` — subscribed and receiving.
+ * - `reconnecting` — dropped after being open; retrying with backoff. Anything the node
+ *   sends meanwhile is lost.
+ * - `closed` — disposed. Final.
+ */
+export type GeeqSocketState = 'connecting' | 'open' | 'reconnecting' | 'closed'
+
+/** One JSON frame from the node, as `{ event, payload }`. */
+export interface GeeqSocketMessage {
+  readonly event: string
+  readonly payload: unknown
+}
+
+export interface GeeqSocketOptions {
+  /**
+   * The node the socket belongs to — normally `chain.endpoint`, which is also where the
+   * transactions go. Its socket is derived: `https://ip:2082` becomes
+   * `wss://ip:2082/ws/`.
+   *
+   * Supply this or {@link url}, not both. Use the node you submit to: only that node
+   * reports a `nonsane` refusal, though every node reports the final verdicts.
+   */
+  readonly endpoint?: string | URL
+  /**
+   * The socket URL itself, when it is not the one derived from the node — a local
+   * harness reaching the socket server directly on its own port, for instance.
+   */
+  readonly url?: string | URL
+  /** Defaults to `new globalThis.WebSocket(url)`. Supply one on Node 20 — see README. */
+  readonly webSocket?: GeeqWebSocketFactory
+  /**
+   * How long a handshake, or a send waiting on one, may take. Defaults to 15000. 0 waits
+   * for ever — including a first handshake that neither opens nor fails.
+   */
+  readonly openTimeoutMs?: number
+  /** How often to send the keepalive `'ping'`. Defaults to 25000; 0 disables it. */
+  readonly heartbeatMs?: number
+  /** Reconnect after a drop. Defaults to true. */
+  readonly reconnect?: boolean
+  /** The first reconnect delay, doubled on each failure. Defaults to 1000. */
+  readonly reconnectDelayMs?: number
+  /** The ceiling on that delay. Defaults to 30000. */
+  readonly maxReconnectDelayMs?: number
+  /** Abandons the first handshake. Once connected, use {@link GeeqSocket.dispose}. */
+  readonly signal?: AbortSignal
+}
+
+export interface GeeqSendOptions {
+  /**
+   * Re-send the frame on every reconnect. A node forgets a connection's subscriptions
+   * when it drops, so anything that subscribes should set this. Only the latest frame for
+   * each event name is kept.
+   */
+  readonly replay?: boolean
+}
+
+export interface GeeqListenOptions {
+  readonly blockNumber?: number
+  /** Defaults to true. */
+  readonly now?: boolean
+}
+
+export interface GeeqTrackOptions {
+  /** How long to wait for a final status. Defaults to 300000. 0 waits for ever. */
+  readonly timeoutMs?: number
+  /** How long a `nonsane` may be overturned by a real verdict. Defaults to 30000. */
+  readonly nonsaneGraceMs?: number
+  /** More accounts to subscribe alongside the signer. */
+  readonly accounts?: readonly (AccountRef | string)[]
+}
+
+/**
+ * Anything with the hash a status event names. Every transaction this SDK builds fits,
+ * and brings its signer's `publicKey` for the subscription.
+ */
+export interface GeeqTrackable {
+  readonly transactionHash: Uint8Array
+  readonly publicKey?: Uint8Array
+}
+
+interface OpenWaiter {
+  resolve(): void
+  reject(error: unknown): void
+}
+
+type Listener<T> = (value: T) => void
+
+function dispatch<T>(listeners: ReadonlySet<Listener<T>> | undefined, value: T): void {
+  if (listeners === undefined) return
+  // A copy, so a listener that removes itself does not skip its neighbour.
+  for (const listener of [...listeners]) {
+    try {
+      listener(value)
+    } catch (error) {
+      reportListenerError(error)
+    }
+  }
+}
+
+function socketUrlOf(options: GeeqSocketOptions): string {
+  const raw =
+    options.url !== undefined
+      ? String(options.url)
+      : socketRoute(originOf(options.endpoint as string | URL))
+  let parsed: URL
+  try {
+    parsed = new URL(raw)
+  } catch (cause) {
+    throw invalidArgument(
+      'url must be an absolute socket URL such as wss://1.2.3.4:2082/ws/, received ' +
+        `${JSON.stringify(raw)}.`,
+      cause,
+    )
+  }
+  if (parsed.protocol !== 'ws:' && parsed.protocol !== 'wss:') {
+    throw invalidArgument(
+      `url must use ws:// or wss://, received ${JSON.stringify(raw)}. To derive the socket ` +
+        'from a node URL, pass it as endpoint instead.',
+    )
+  }
+  return parsed.href
+}
+
+/**
+ * Every key a node might file an account's events under.
+ *
+ * Nodes have keyed per-account events by the base64 public key and, since 2026-09, by the
+ * base64 account id; which one a socket server matches is not visible from here. So an
+ * account named by its public key is subscribed under both, as the production wallet does.
+ */
+function keysOf(ref: AccountRef | string): string[] {
+  if (typeof ref === 'string') {
+    const bytes = fromBase64(ref, 'account key')
+    if (bytes.length !== KEY_BYTES) {
+      throw invalidArgument(
+        `An account key must be the base64 of a ${KEY_BYTES}-byte public key or account id, ` +
+          `received ${bytes.length} bytes.`,
+      )
+    }
+    return [ref]
+  }
+
+  const accountId = toBase64(resolveAccountId(ref))
+  if (ref instanceof Uint8Array) return [accountId]
+
+  const { publicKey } = ref as { publicKey?: unknown }
+  if (publicKey === undefined) return [accountId]
+  if (!(publicKey instanceof Uint8Array) || publicKey.length !== KEY_BYTES) {
+    throw invalidKey(`publicKey must be ${KEY_BYTES} bytes.`)
+  }
+  return [toBase64(publicKey), accountId]
+}
+
+function closeQuietly(socket: GeeqWebSocketLike | null): void {
+  if (socket === null) return
+  try {
+    socket.close()
+  } catch {
+    // Already closing, or never opened. Either way there is nothing left to release.
+  }
+}
+
+/**
+ * A node's WebSocket: the channel through which it reports what happened to the
+ * transactions you sent, and pushes account and chain updates.
+ *
+ * One class for every use an application has for the socket:
+ *
+ * - {@link track} a transaction you are about to submit, and get its verdict;
+ * - {@link subscribe} to accounts and read their events with {@link on};
+ * - {@link send} any frame the node understands, and receive any it sends.
+ *
+ * The protocol's hazards are handled here, once: subscriptions replace rather than add,
+ * so the full set of keys is always sent; the node forgets a connection's subscriptions
+ * when it drops, so they are replayed on every reconnect before anything is announced;
+ * the edge proxy drops an idle socket, so it is kept alive; a transaction's first status
+ * is not always its last, so {@link GeeqTrackedTx} decides when it is final.
+ *
+ * ```ts
+ * const socket = await GeeqSocket.connect({ endpoint: chain.endpoint })
+ * const tx = await chain.createTransfer({ from, to, amount })
+ * const tracked = await socket.track(tx)          // before submitting — always
+ * const response = await fetch(submitRoute(tx.nodeUrl), { … })
+ * if (!response.ok) tracked.refused({ status: response.status })
+ * const outcome = await tracked.settled()
+ * ```
+ *
+ * In a reactive framework, mark an instance raw (Vue's `markRaw`) rather than letting it
+ * be proxied — a proxied native WebSocket throws on every call.
+ */
+export class GeeqSocket {
+  /** The socket URL, normalised. */
+  readonly url: string
+
+  // TS-private and non-enumerable, never `#private` — see GeeqNode for why.
+  private readonly factory!: GeeqWebSocketFactory
+  private readonly openTimeoutMs!: number
+  private readonly heartbeatMs!: number
+  private readonly reconnects!: boolean
+  private readonly reconnectDelayMs!: number
+  private readonly maxReconnectDelayMs!: number
+  /** The frames in force, by event name, replayed on every connection. */
+  private readonly persisted!: Map<string, string>
+  /** What this connection has already been told, so a repeat is not sent twice. */
+  private readonly told!: Map<string, string>
+  private readonly keys!: Set<string>
+  private readonly tracked!: Map<string, GeeqTrackedTx>
+  private readonly eventListeners!: Map<string, Set<Listener<unknown>>>
+  private readonly messageListeners!: Set<Listener<GeeqSocketMessage>>
+  private readonly statusListeners!: Set<Listener<GeeqTxStatusEvent>>
+  private readonly stateListeners!: Set<Listener<GeeqSocketState>>
+  private readonly waiters!: Set<OpenWaiter>
+  private socket!: GeeqWebSocketLike | null
+  private current!: GeeqSocketState
+  private everOpened!: boolean
+  private attempts!: number
+  private openTimer!: ReturnType<typeof setTimeout> | null
+  private reconnectTimer!: ReturnType<typeof setTimeout> | null
+  private heartbeatTimer!: ReturnType<typeof setInterval> | null
+
+  /** @internal */
+  constructor(init: {
+    url: string
+    factory: GeeqWebSocketFactory
+    openTimeoutMs: number
+    heartbeatMs: number
+    reconnect: boolean
+    reconnectDelayMs: number
+    maxReconnectDelayMs: number
+  }) {
+    this.url = init.url
+
+    const hidden = (key: string, value: unknown, writable = false): void => {
+      Object.defineProperty(this, key, { value, enumerable: false, writable })
+    }
+    hidden('factory', init.factory)
+    hidden('openTimeoutMs', init.openTimeoutMs)
+    hidden('heartbeatMs', init.heartbeatMs)
+    hidden('reconnects', init.reconnect)
+    hidden('reconnectDelayMs', init.reconnectDelayMs)
+    hidden('maxReconnectDelayMs', init.maxReconnectDelayMs)
+    hidden('persisted', new Map())
+    hidden('told', new Map())
+    hidden('keys', new Set())
+    hidden('tracked', new Map())
+    hidden('eventListeners', new Map())
+    hidden('messageListeners', new Set())
+    hidden('statusListeners', new Set())
+    hidden('stateListeners', new Set())
+    hidden('waiters', new Set())
+    hidden('socket', null, true)
+    hidden('current', 'connecting', true)
+    hidden('everOpened', false, true)
+    hidden('attempts', 0, true)
+    hidden('openTimer', null, true)
+    hidden('reconnectTimer', null, true)
+    hidden('heartbeatTimer', null, true)
+  }
+
+  /**
+   * Open a node's socket and resolve once it is open.
+   *
+   * Throws `socket-unreachable` if the first handshake fails, rather than retrying
+   * quietly: a socket that never opened is almost always a certificate, a mixed-content
+   * page or a wrong URL, and retrying hides which. After that first open, a drop is
+   * retried automatically and reported through {@link onConnectionChange}.
+   */
+  static async connect(options: GeeqSocketOptions): Promise<GeeqSocket> {
+    if ((options.endpoint === undefined) === (options.url === undefined)) {
+      throw invalidArgument(
+        'Provide exactly one of endpoint (the node you submit to — its socket URL is ' +
+          'derived from it) or url (a socket URL, such as ws://10.0.0.1:3100/ws/ for a ' +
+          'local harness).',
+      )
+    }
+    assertDuration(options.openTimeoutMs, 'openTimeoutMs')
+    assertDuration(options.heartbeatMs, 'heartbeatMs')
+    assertDuration(options.reconnectDelayMs, 'reconnectDelayMs')
+    assertDuration(options.maxReconnectDelayMs, 'maxReconnectDelayMs')
+
+    const url = socketUrlOf(options)
+    assertSocketSchemeReachable(url)
+
+    const { signal } = options
+    if (signal?.aborted === true) throw signal.reason
+
+    const socket = new GeeqSocket({
+      url,
+      factory: options.webSocket ?? defaultWebSocketFactory,
+      openTimeoutMs: options.openTimeoutMs ?? DEFAULT_OPEN_TIMEOUT_MS,
+      heartbeatMs: options.heartbeatMs ?? DEFAULT_HEARTBEAT_MS,
+      reconnect: options.reconnect ?? true,
+      reconnectDelayMs: options.reconnectDelayMs ?? DEFAULT_RECONNECT_DELAY_MS,
+      maxReconnectDelayMs: options.maxReconnectDelayMs ?? DEFAULT_MAX_RECONNECT_DELAY_MS,
+    })
+
+    let onAbort: (() => void) | undefined
+    try {
+      await new Promise<void>((resolve, reject) => {
+        // No timer of its own: the handshake's timeout is the deadline.
+        socket.waiters.add({ resolve, reject })
+        if (signal !== undefined) {
+          onAbort = () => reject(signal.reason)
+          signal.addEventListener('abort', onAbort)
+        }
+        socket.dial()
+      })
+    } catch (error) {
+      socket.dispose()
+      throw error
+    } finally {
+      if (onAbort !== undefined) signal?.removeEventListener('abort', onAbort)
+    }
+    return socket
+  }
+
+  /** Where the connection stands. See {@link GeeqSocketState}. */
+  get state(): GeeqSocketState {
+    return this.current
+  }
+
+  /** Every account key subscribed so far, base64. The set only grows. */
+  get subscriptions(): readonly string[] {
+    return [...this.keys]
+  }
+
+  /**
+   * Subscribe to accounts' events: their transactions' statuses and record updates.
+   *
+   * Takes a keypair, a `{ publicKey }`, a 32-byte account id, a base64 key, or a list of
+   * them. The node has no unsubscribe and treats every subscription as a replacement, so
+   * this adds to the set this socket holds and sends all of it — calling it for one
+   * account never silences another. Resolves once the node has been told.
+   */
+  async subscribe(
+    accounts: AccountRef | string | readonly (AccountRef | string)[],
+  ): Promise<void> {
+    this.assertOpenable('subscribe')
+    const list = (Array.isArray(accounts) ? accounts : [accounts]) as readonly (
+      | AccountRef
+      | string
+    )[]
+    // Resolve every key before adding any, so one bad entry does not half-apply the list.
+    const resolved = list.flatMap(keysOf)
+    for (const key of resolved) this.keys.add(key)
+    return this.send('client', { publicKeys: [...this.keys] }, { replay: true })
+  }
+
+  /** Ask for events from now, or from a block. Replayed on reconnect. */
+  async listen(options: GeeqListenOptions = {}): Promise<void> {
+    const { blockNumber } = options
+    if (
+      blockNumber !== undefined &&
+      (!Number.isInteger(blockNumber) || blockNumber < 0 || blockNumber > MAX_UINT32)
+    ) {
+      throw invalidArgument(
+        `blockNumber must be a block number, received ${String(blockNumber)}.`,
+      )
+    }
+    return this.send(
+      'listen',
+      { ...(blockNumber === undefined ? {} : { blockNumber }), now: options.now ?? true },
+      { replay: true },
+    )
+  }
+
+  /**
+   * Subscribe to the whole chain's record feed — every account, fee and parameter update.
+   * What a block explorer or an indexer wants; an ordinary application does not.
+   */
+  async subscribeBlockExplorer(): Promise<void> {
+    return this.send('block-explorer', undefined, { replay: true })
+  }
+
+  /**
+   * Send a frame, `{ event, payload }`, waiting for the connection if it is down.
+   *
+   * The escape hatch for anything the node understands that this class has no method
+   * for. Rejects with `socket-unreachable` if the socket does not reopen within
+   * `openTimeoutMs` — a replayed frame is still kept, and goes out when it does.
+   */
+  async send(event: string, payload?: unknown, options: GeeqSendOptions = {}): Promise<void> {
+    this.assertOpenable('send')
+    if (typeof event !== 'string' || event === '') {
+      throw invalidArgument('event must be a non-empty string.')
+    }
+    const frame = JSON.stringify(payload === undefined ? { event } : { event, payload })
+    const replay = options.replay === true
+    if (replay) this.persisted.set(event, frame)
+
+    // Resolves only once the frame has actually gone out. A socket can be open by our
+    // books and already closing by its own — its close event not yet delivered — and a
+    // subscription reported as sent when it was not would break track()'s promise.
+    for (;;) {
+      await this.whenOpen()
+      // A newer frame for the same event may have replaced this one while we waited; the
+      // node must end up with the newest, and a replacement makes the older one moot.
+      const latest = replay ? (this.persisted.get(event) ?? frame) : frame
+      if (this.transmit(event, latest, replay)) return
+    }
+  }
+
+  /**
+   * Follow a transaction to its verdict. Call it **before** submitting.
+   *
+   * Subscribes the signer — the node pushes a transaction's statuses only to connections
+   * subscribed to its account — and resolves once the node has been told, so a status
+   * cannot arrive before anyone is listening for it. If this throws, do not submit: a
+   * transaction sent with no way to hear its verdict leaves the user guessing.
+   *
+   * Tracking the same transaction twice returns the same handle.
+   */
+  async track(tx: GeeqTrackable, options: GeeqTrackOptions = {}): Promise<GeeqTrackedTx> {
+    this.assertOpenable('track')
+    const hash = (tx as { transactionHash?: unknown } | null)?.transactionHash
+    if (!(hash instanceof Uint8Array) || hash.length !== KEY_BYTES) {
+      throw invalidArgument(
+        `tx must carry a ${KEY_BYTES}-byte transactionHash — pass the transaction the SDK ` +
+          'built.',
+      )
+    }
+    assertDuration(options.timeoutMs, 'timeoutMs')
+    assertDuration(options.nonsaneGraceMs, 'nonsaneGraceMs')
+
+    const accounts: (AccountRef | string)[] = [
+      ...(tx.publicKey === undefined ? [] : [{ publicKey: tx.publicKey }]),
+      ...(options.accounts ?? []),
+    ]
+    if (accounts.length === 0) {
+      throw invalidArgument(
+        'This transaction does not say who signed it, so there is no account to subscribe ' +
+          'to for its status. Pass the signer in accounts.',
+      )
+    }
+
+    const id = toBase64(hash)
+    const existing = this.tracked.get(id)
+    const tracked =
+      existing ??
+      new GeeqTrackedTx({
+        id,
+        timeoutMs: options.timeoutMs ?? DEFAULT_TRACK_TIMEOUT_MS,
+        nonsaneGraceMs: options.nonsaneGraceMs ?? DEFAULT_NONSANE_GRACE_MS,
+        detach: () => {
+          if (this.tracked.get(id) === tracked) this.tracked.delete(id)
+        },
+      })
+    // Registered before the subscription goes out, so nothing can slip between them.
+    this.tracked.set(id, tracked)
+
+    try {
+      await this.subscribe(accounts)
+    } catch (error) {
+      if (existing === undefined) tracked.release()
+      throw error
+    }
+    return tracked
+  }
+
+  /**
+   * Call `listener` with the payload of every frame named `event`, whatever it is —
+   * `'uut_status'`, `'coin-account-update'`, `'fee-update'`, or one this SDK has never
+   * heard of. Returns the function that removes it.
+   */
+  on(event: string, listener: (payload: unknown) => void): () => void {
+    let listeners = this.eventListeners.get(event)
+    if (listeners === undefined) {
+      listeners = new Set()
+      this.eventListeners.set(event, listeners)
+    }
+    const set = listeners
+    set.add(listener)
+    return () => {
+      set.delete(listener)
+      if (set.size === 0 && this.eventListeners.get(event) === set) {
+        this.eventListeners.delete(event)
+      }
+    }
+  }
+
+  /** Call `listener` with every JSON frame the node sends. */
+  onMessage(listener: (message: GeeqSocketMessage) => void): () => void {
+    this.messageListeners.add(listener)
+    return () => {
+      this.messageListeners.delete(listener)
+    }
+  }
+
+  /** Call `listener` with every transaction status, tracked or not, already parsed. */
+  onTxStatus(listener: (event: GeeqTxStatusEvent) => void): () => void {
+    this.statusListeners.add(listener)
+    return () => {
+      this.statusListeners.delete(listener)
+    }
+  }
+
+  /** Call `listener` whenever {@link state} changes. */
+  onConnectionChange(listener: (state: GeeqSocketState) => void): () => void {
+    this.stateListeners.add(listener)
+    return () => {
+      this.stateListeners.delete(listener)
+    }
+  }
+
+  /**
+   * Close for good. Pending sends reject with `socket-closed`, and every transaction still
+   * being tracked settles `unknown` with reason `closed` — it may yet be decided, just
+   * not heard about here.
+   */
+  dispose(): void {
+    if (this.current === 'closed') return
+    this.setState('closed')
+
+    for (const timer of [this.openTimer, this.reconnectTimer]) {
+      if (timer !== null) clearTimeout(timer)
+    }
+    this.openTimer = null
+    this.reconnectTimer = null
+    this.stopHeartbeat()
+
+    const socket = this.socket
+    this.socket = null
+    closeQuietly(socket)
+
+    const closed = socketClosed(`The socket at ${this.url} was disposed.`)
+    for (const waiter of [...this.waiters]) waiter.reject(closed)
+    this.waiters.clear()
+
+    for (const tracked of [...this.tracked.values()]) {
+      tracked.abandon(
+        'closed',
+        `The socket was closed while transaction ${tracked.id} was pending. It may still be ` +
+          'decided; check the ledger before sending it again.',
+      )
+    }
+    this.tracked.clear()
+
+    this.eventListeners.clear()
+    this.messageListeners.clear()
+    this.statusListeners.clear()
+    this.stateListeners.clear()
+  }
+
+  toJSON(): Record<string, unknown> {
+    return {
+      url: this.url,
+      state: this.current,
+      subscriptions: this.keys.size,
+      tracking: this.tracked.size,
+    }
+  }
+
+  toString(): string {
+    return `GeeqSocket(${this.url}, ${this.current})`
+  }
+
+  private assertOpenable(what: string): void {
+    if (this.current === 'closed') {
+      throw socketClosed(
+        `${what}() was called on a disposed socket (${this.url}). Connect a new one.`,
+      )
+    }
+  }
+
+  private setState(next: GeeqSocketState): void {
+    if (this.current === next) return
+    this.current = next
+    dispatch(this.stateListeners, next)
+  }
+
+  /** Resolves when the socket is open, or rejects after `openTimeoutMs` or on dispose. */
+  private whenOpen(): Promise<void> {
+    if (this.current === 'open') return Promise.resolve()
+    if (this.current === 'closed') {
+      return Promise.reject(socketClosed(`The socket at ${this.url} was disposed.`))
+    }
+
+    return new Promise<void>((resolve, reject) => {
+      let timer: ReturnType<typeof setTimeout> | null = null
+      const waiter: OpenWaiter = {
+        resolve: () => {
+          if (timer !== null) clearTimeout(timer)
+          resolve()
+        },
+        reject: (error) => {
+          if (timer !== null) clearTimeout(timer)
+          reject(error)
+        },
+      }
+      if (this.openTimeoutMs > 0) {
+        timer = setTimeout(() => {
+          this.waiters.delete(waiter)
+          reject(
+            socketUnreachable(
+              `The socket at ${this.url} is ${this.current} and did not reopen within ` +
+                `${this.openTimeoutMs}ms. It keeps retrying; anything sent with replay ` +
+                'will go out when it does.',
+            ),
+          )
+        }, this.openTimeoutMs)
+      }
+      this.waiters.add(waiter)
+    })
+  }
+
+  private dial(): void {
+    let socket: GeeqWebSocketLike
+    try {
+      socket = this.factory(this.url)
+    } catch (cause) {
+      this.attemptFailed(
+        cause instanceof GeeqError
+          ? cause
+          : socketUnreachable(opaqueSocketFailureMessage(this.url), cause),
+      )
+      return
+    }
+
+    this.socket = socket
+    // A new connection has been told nothing, so nothing may be suppressed as a repeat.
+    this.told.clear()
+
+    if (this.openTimeoutMs > 0) {
+      this.openTimer = setTimeout(() => {
+        if (this.socket !== socket) return
+        this.socket = null
+        closeQuietly(socket)
+        this.attemptFailed(
+          socketUnreachable(
+            `The socket at ${this.url} did not open within ${this.openTimeoutMs}ms. ` +
+              opaqueSocketFailureMessage(this.url),
+          ),
+        )
+      }, this.openTimeoutMs)
+    }
+
+    // A superseded socket can still fire; only the current one may drive state.
+    socket.addEventListener('open', () => {
+      if (this.socket === socket) this.opened()
+    })
+    socket.addEventListener('message', (event) => {
+      if (this.socket === socket) this.receive(event.data)
+    })
+    socket.addEventListener('close', () => {
+      if (this.socket !== socket) return
+      this.socket = null
+      this.attemptFailed(socketUnreachable(opaqueSocketFailureMessage(this.url)))
+    })
+    socket.addEventListener('error', () => {
+      // A 'close' always follows, and that is where the drop is handled. The listener
+      // must still exist: the `ws` package throws an unhandled 'error' otherwise.
+    })
+  }
+
+  private opened(): void {
+    if (this.openTimer !== null) clearTimeout(this.openTimer)
+    this.openTimer = null
+    this.everOpened = true
+
+    // Restore everything this connection should hold before announcing it, so a listener
+    // reacting to 'open' finds the subscriptions already in force. If it drops part way,
+    // the next connection replays the lot.
+    for (const [event, frame] of this.persisted) {
+      if (!this.transmit(event, frame, true)) return
+    }
+    // Only now is it a working connection. Resetting the backoff any earlier would let a
+    // connection that dies while its subscriptions are replayed be redialled every second
+    // for ever.
+    this.attempts = 0
+    this.startHeartbeat()
+    this.setState('open')
+
+    for (const waiter of [...this.waiters]) waiter.resolve()
+    this.waiters.clear()
+  }
+
+  /** A handshake failed, or an open socket dropped. */
+  private attemptFailed(error: GeeqError): void {
+    if (this.openTimer !== null) clearTimeout(this.openTimer)
+    this.openTimer = null
+    this.stopHeartbeat()
+    if (this.current === 'closed') return
+
+    if (!this.everOpened) {
+      // Still inside connect(): report it, and let connect() dispose.
+      for (const waiter of [...this.waiters]) waiter.reject(error)
+      this.waiters.clear()
+      return
+    }
+
+    if (!this.reconnects) {
+      this.dispose()
+      return
+    }
+
+    this.setState('reconnecting')
+    if (this.reconnectTimer !== null) return
+    const delay = Math.min(this.reconnectDelayMs * 2 ** this.attempts, this.maxReconnectDelayMs)
+    this.attempts += 1
+    this.reconnectTimer = setTimeout(() => {
+      this.reconnectTimer = null
+      if (this.current !== 'closed') this.dial()
+    }, delay)
+  }
+
+  /**
+   * Put one frame on the current connection. True once it is there — or already was.
+   *
+   * False means the connection is gone. If our books still said it was open, it is
+   * treated as the drop it is, here and now, so the caller waits for the next connection
+   * instead of spinning on this one.
+   */
+  private transmit(event: string, frame: string, dedupe: boolean): boolean {
+    // The node treats every subscription frame as a fresh subscribe, so an identical
+    // repeat on the same connection is dropped here instead.
+    if (dedupe && this.told.get(event) === frame) return true
+
+    const socket = this.socket
+    if (socket === null) return false
+    if (socket.readyState === WEBSOCKET_OPEN) {
+      try {
+        socket.send(frame)
+        if (dedupe) this.told.set(event, frame)
+        return true
+      } catch {
+        // Closing underneath us. Handled below, as for any other drop.
+      }
+    }
+
+    this.socket = null
+    closeQuietly(socket)
+    this.attemptFailed(socketUnreachable(opaqueSocketFailureMessage(this.url)))
+    return false
+  }
+
+  private receive(data: unknown): void {
+    const text =
+      typeof data === 'string'
+        ? data
+        : data instanceof ArrayBuffer || ArrayBuffer.isView(data)
+          ? new TextDecoder().decode(data)
+          : undefined
+    if (text === undefined) return
+
+    let parsed: unknown
+    try {
+      parsed = JSON.parse(text)
+    } catch {
+      // Heartbeat replies and other non-JSON frames are not events.
+      return
+    }
+    if (parsed === null || typeof parsed !== 'object') return
+    const { event, payload } = parsed as { event?: unknown; payload?: unknown }
+    if (typeof event !== 'string') return
+
+    dispatch(this.messageListeners, Object.freeze({ event, payload }))
+    dispatch(this.eventListeners.get(event), payload)
+
+    if (event !== 'uut_status') return
+    const status = parseTxStatus(payload)
+    if (status === undefined) return
+    dispatch(this.statusListeners, status)
+    this.tracked.get(status.id)?.receive(status)
+  }
+
+  private startHeartbeat(): void {
+    this.stopHeartbeat()
+    if (this.heartbeatMs <= 0) return
+    this.heartbeatTimer = setInterval(() => {
+      const socket = this.socket
+      if (socket === null || socket.readyState !== WEBSOCKET_OPEN) return
+      try {
+        // A raw text frame, not JSON: there is no protocol ping, and a browser cannot send
+        // a control frame. Any reply is non-JSON and ignored.
+        socket.send('ping')
+      } catch {
+        // The close handler reconnects.
+      }
+    }, this.heartbeatMs)
+  }
+
+  private stopHeartbeat(): void {
+    if (this.heartbeatTimer !== null) clearInterval(this.heartbeatTimer)
+    this.heartbeatTimer = null
+  }
+}