core: define and handle ws errors

Author: sehyunc

packages/core/package.json

@@ -72,6 +72,7 @@
   "dependencies": {
     "axios": "^1.6.8",
     "isomorphic-ws": "^5.0.0",
+    "isows": "^1.0.6",
     "json-bigint": "^1.0.0",
     "tiny-invariant": "^1.3.3",
     "zustand": "^4.5.2"

packages/core/src/errors/base.ts

@@ -1,65 +1,46 @@
 import { getVersion } from '../utils/getVersion.js'
 
-import type { Evaluate, OneOf } from '../types/utils.js'
-
 export type ErrorType<name extends string = 'Error'> = Error & { name: name }
 
-type BaseErrorOptions = Evaluate<
-  OneOf<{ details?: string | undefined } | { cause: BaseError | Error }> & {
-    docsPath?: string | undefined
-    docsSlug?: string | undefined
-    metaMessages?: string[] | undefined
-  }
->
+type BaseErrorParameters = {
+  cause?: BaseError | Error | undefined
+  details?: string | undefined
+  metaMessages?: string[] | undefined
+  name?: string | undefined
+}
 
 export type BaseErrorType = BaseError & { name: 'RenegadeCoreError' }
 export class BaseError extends Error {
   details: string
-  docsPath?: string | undefined
   metaMessages?: string[] | undefined
   shortMessage: string
 
   override name = 'RenegadeCoreError'
-  get docsBaseUrl() {
-    return 'todo: put a docs link here'
-  }
   get version() {
     return getVersion()
   }
 
-  constructor(shortMessage: string, options: BaseErrorOptions = {}) {
+  constructor(shortMessage: string, args: BaseErrorParameters = {}) {
     super()
 
     const details =
-      options.cause instanceof BaseError
-        ? options.cause.details
-        : options.cause?.message
-          ? options.cause.message
-          : options.details!
-    const docsPath =
-      options.cause instanceof BaseError
-        ? options.cause.docsPath || options.docsPath
-        : options.docsPath
+      args.cause instanceof BaseError
+        ? args.cause.details
+        : args.cause?.message
+          ? args.cause.message
+          : args.details!
 
     this.message = [
       shortMessage || 'An error occurred.',
       '',
-      ...(options.metaMessages ? [...options.metaMessages, ''] : []),
-      ...(docsPath
-        ? [
-            `Docs: ${this.docsBaseUrl}${docsPath}.html${
-              options.docsSlug ? `#${options.docsSlug}` : ''
-            }`,
-          ]
-        : []),
+      ...(args.metaMessages ? [...args.metaMessages, ''] : []),
       ...(details ? [`Details: ${details}`] : []),
       `Version: ${this.version}`,
     ].join('\n')
 
-    if (options.cause) this.cause = options.cause
+    if (args.cause) this.cause = args.cause
     this.details = details
-    this.docsPath = docsPath
-    this.metaMessages = options.metaMessages
+    this.metaMessages = args.metaMessages
     this.shortMessage = shortMessage
   }
 

packages/core/src/errors/websocket.ts

@@ -0,0 +1,67 @@
+import { BaseError } from './base.js'
+
+export type SocketClosedErrorType = SocketClosedError & {
+  name: 'SocketClosedError'
+}
+export class SocketClosedError extends BaseError {
+  constructor({
+    url,
+  }: {
+    url?: string | undefined
+  } = {}) {
+    super('The socket has been closed.', {
+      metaMessages: [url && `URL: ${url}`].filter(Boolean) as string[],
+      name: 'SocketClosedError',
+    })
+  }
+}
+
+export type WebSocketRequestErrorType = WebSocketRequestError & {
+  name: 'WebSocketRequestError'
+}
+export class WebSocketRequestError extends BaseError {
+  constructor({
+    body,
+    cause,
+    details,
+    url,
+  }: {
+    body?: { [key: string]: unknown } | undefined
+    cause?: Error | undefined
+    details?: string | undefined
+    url: string
+  }) {
+    super('WebSocket request failed.', {
+      cause,
+      details,
+      metaMessages: [
+        `URL: ${url}`,
+        body && `Request body: ${JSON.stringify(body)}`,
+      ].filter(Boolean) as string[],
+      name: 'WebSocketRequestError',
+    })
+  }
+}
+
+export type WebSocketConnectionErrorType = WebSocketConnectionError & {
+  name: 'WebSocketConnectionError'
+}
+
+export class WebSocketConnectionError extends BaseError {
+  constructor({
+    url,
+    cause,
+    details,
+  }: {
+    url: string
+    cause?: Error | undefined
+    details?: string | undefined
+  }) {
+    super('Failed to establish WebSocket connection.', {
+      cause,
+      details,
+      metaMessages: [`URL: ${url}`],
+      name: 'WebSocketConnectionError',
+    })
+  }
+}

packages/core/src/utils/websocket.ts

@@ -1,5 +1,10 @@
 import { SIG_EXPIRATION_BUFFER_MS } from '../constants.js'
 import type { RenegadeConfig } from '../createConfig.js'
+import {
+  SocketClosedError,
+  WebSocketConnectionError,
+  WebSocketRequestError,
+} from '../errors/websocket.js'
 import { addExpiringAuthToHeaders } from './http.js'
 
 export enum AuthType {
@@ -48,6 +53,24 @@ export class RelayerWebsocket {
 
   private ws: WebSocket | null = null
 
+  private handleOpen = (event: Event) => {
+    if (!this.ws) return
+    const message = this.buildSubscriptionMessage()
+    this.request(message)
+
+    return this.onopenCallback?.call(this.ws, event)
+  }
+
+  private handleClose = (event: CloseEvent) => {
+    this.cleanup()
+    return this.oncloseCallback?.call(this.ws!, event)
+  }
+
+  private handleError = async (event: Event) => {
+    this.cleanup()
+    return this.onerrorCallback?.call(this.ws!, event)
+  }
+
   constructor(params: RelayerWebsocketParams) {
     this.config = params.config
     this.topic = params.topic
@@ -62,33 +85,35 @@ export class RelayerWebsocket {
   // | Public API |
   // --------------
 
-  public connect(): void {
+  public async connect(): Promise<void> {
     if (this.ws) {
       throw new Error(
         'WebSocket connection attempt aborted: already connected.',
       )
     }
 
-    const instance = this
-    instance.ws = new WebSocket(this.config.getWebsocketBaseUrl())
-
-    instance.ws.onopen = function (this: WebSocket, event: Event) {
-      const message = instance.buildSubscriptionMessage()
-      this.send(JSON.stringify(message))
-
-      return instance.onopenCallback?.call(this, event)
-    }
-
-    instance.ws.onmessage = instance.onmessage
-
-    instance.ws.onclose = function (this: WebSocket, event: CloseEvent) {
-      instance.cleanup()
-      return instance.oncloseCallback?.call(this, event)
-    }
-
-    instance.ws.onerror = function (this: WebSocket, event: Event) {
-      instance.cleanup()
-      return instance.onerrorCallback?.call(this, event)
+    const WebSocket = await import('isows').then((module) => module.WebSocket)
+    const url = this.config.getWebsocketBaseUrl()
+    this.ws = new WebSocket(url)
+
+    this.ws.addEventListener('open', this.handleOpen)
+    this.ws.addEventListener('message', this.onmessage)
+    this.ws.addEventListener('close', this.handleClose)
+    this.ws.addEventListener('error', this.handleError)
+
+    // Wait for the socket to open.
+    if (this.ws?.readyState === WebSocket.CONNECTING) {
+      await new Promise((resolve, reject) => {
+        if (!this.ws) return
+        this.ws.onopen = (event) => resolve(event)
+        this.ws.onerror = (error) =>
+          reject(
+            new WebSocketConnectionError({
+              url,
+              cause: error as unknown as Error,
+            }),
+          )
+      })
     }
   }
 
@@ -98,7 +123,7 @@ export class RelayerWebsocket {
     }
 
     const message = this.buildUnsubscriptionMessage()
-    this.ws.send(JSON.stringify(message))
+    this.request(message)
 
     this.ws.close()
   }
@@ -107,6 +132,21 @@ export class RelayerWebsocket {
   // | Private API |
   // ---------------
 
+  private request(message: SubscriptionMessage | UnsubscriptionMessage): void {
+    if (
+      this.ws?.readyState === this.ws?.CLOSED ||
+      this.ws?.readyState === this.ws?.CLOSING
+    ) {
+      throw new WebSocketRequestError({
+        body: message,
+        url: this.ws?.url || '',
+        cause: new SocketClosedError({ url: this.ws?.url }),
+      })
+    }
+
+    this.ws?.send(JSON.stringify(message))
+  }
+
   private buildSubscriptionMessage(): SubscriptionMessage {
     const body = {
       method: 'subscribe' as const,
@@ -147,6 +187,15 @@ export class RelayerWebsocket {
   }
 
   private cleanup(): void {
+    // Remove all event listeners before nullifying the reference
+    if (this.ws) {
+      this.ws.removeEventListener('open', this.handleOpen)
+      this.ws.removeEventListener('message', this.onmessage)
+      this.ws.removeEventListener('close', this.handleClose)
+      this.ws.removeEventListener('error', this.handleError)
+    }
+
+    // Nullify the WebSocket instance
     this.ws = null
   }
 }

packages/core/src/utils/websocketWaiter.ts

@@ -66,16 +66,16 @@ export async function websocketWaiter<T>(
           reject(new Error('Websocket connection closed'))
         }
       },
-      onerrorCallback: (event: Event) => {
+      onerrorCallback: (error: Event | Error) => {
         if (!promiseSettled) {
           promiseSettled = true
-          reject(event)
+          reject(error)
         }
       },
     }
 
     const ws = new RelayerWebsocket(wsParams)
-    ws.connect()
+    ws.connect().catch((error) => reject(error))
 
     if (params.timeout) {
       setTimeout(() => {

packages/react/src/errors/base.ts

@@ -5,9 +5,6 @@ import { getVersion } from '../utils/getVersion.js'
 export type BaseErrorType = BaseError & { name: 'RenegadeError' }
 export class BaseError extends CoreError {
   override name = 'RenegadeError'
-  override get docsBaseUrl() {
-    return 'todo: put a docs link here'
-  }
   override get version() {
     return getVersion()
   }

packages/react/src/errors/context.ts

@@ -7,8 +7,6 @@ export type RenegadeProviderNotFoundErrorType =
 export class RenegadeProviderNotFoundError extends BaseError {
   override name = 'RenegadeProviderNotFoundError'
   constructor() {
-    super('`useConfig` must be used within `RenegadeProvider`.', {
-      docsPath: '/api/RenegadeProvider',
-    })
+    super('`useConfig` must be used within `RenegadeProvider`.')
   }
 }