xrpl 2.10.0 → 2.11.0

package/src/client/ExponentialBackoff.ts

@@ -0,0 +1,71 @@
+/*
+ * Original code based on "backo" - https://github.com/segmentio/backo
+ * MIT License - Copyright 2014 Segment.io
+ * Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation
+ * files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy,
+ * modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software
+ * is furnished to do so, subject to the following conditions:
+ * The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE
+ * WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
+ * COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE,
+ * ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+ */
+
+interface ExponentialBackoffOptions {
+  // The min backoff duration.
+  min?: number
+  // The max backoff duration.
+  max?: number
+}
+
+const DEFAULT_MIN = 100
+const DEFAULT_MAX = 1000
+
+/**
+ * A Back off strategy that increases exponentially. Useful with repeated
+ * setTimeout calls over a network (where the destination may be down).
+ */
+export default class ExponentialBackoff {
+  private readonly ms: number
+  private readonly max: number
+  private readonly factor: number = 2
+  private numAttempts = 0
+
+  /**
+   * Constructs an ExponentialBackoff object.
+   *
+   * @param opts - The options for the object.
+   */
+  public constructor(opts: ExponentialBackoffOptions = {}) {
+    this.ms = opts.min ?? DEFAULT_MIN
+    this.max = opts.max ?? DEFAULT_MAX
+  }
+
+  /**
+   * Number of attempts for backoff so far.
+   *
+   * @returns Number of attempts.
+   */
+  public get attempts(): number {
+    return this.numAttempts
+  }
+
+  /**
+   * Return the backoff duration.
+   *
+   * @returns The backoff duration in milliseconds.
+   */
+  public duration(): number {
+    const ms = this.ms * this.factor ** this.numAttempts
+    this.numAttempts += 1
+    return Math.floor(Math.min(ms, this.max))
+  }
+
+  /**
+   * Reset the number of attempts.
+   */
+  public reset(): void {
+    this.numAttempts = 0
+  }
+}

package/src/client/RequestManager.ts

@@ -0,0 +1,194 @@
+import {
+  ResponseFormatError,
+  RippledError,
+  TimeoutError,
+  XrplError,
+} from '../errors'
+import { Response } from '../models/methods'
+import { BaseRequest, ErrorResponse } from '../models/methods/baseMethod'
+
+/**
+ * Manage all the requests made to the websocket, and their async responses
+ * that come in from the WebSocket. Responses come in over the WS connection
+ * after-the-fact, so this manager will tie that response to resolve the
+ * original request.
+ */
+export default class RequestManager {
+  private nextId = 0
+  private readonly promisesAwaitingResponse = new Map<
+    string | number,
+    {
+      resolve: (value: Response | PromiseLike<Response>) => void
+      reject: (value: Error) => void
+      timer: ReturnType<typeof setTimeout>
+    }
+  >()
+
+  /**
+   * Successfully resolves a request.
+   *
+   * @param id - ID of the request.
+   * @param response - Response to return.
+   * @throws Error if no existing promise with the given ID.
+   */
+  public resolve(id: string | number, response: Response): void {
+    const promise = this.promisesAwaitingResponse.get(id)
+    if (promise == null) {
+      throw new XrplError(`No existing promise with id ${id}`, {
+        type: 'resolve',
+        response,
+      })
+    }
+    clearTimeout(promise.timer)
+    promise.resolve(response)
+    this.deletePromise(id)
+  }
+
+  /**
+   * Rejects a request.
+   *
+   * @param id - ID of the request.
+   * @param error - Error to throw with the reject.
+   * @throws Error if no existing promise with the given ID.
+   */
+  public reject(id: string | number, error: Error): void {
+    const promise = this.promisesAwaitingResponse.get(id)
+    if (promise == null) {
+      throw new XrplError(`No existing promise with id ${id}`, {
+        type: 'reject',
+        error,
+      })
+    }
+    clearTimeout(promise.timer)
+    // TODO: figure out how to have a better stack trace for an error
+    promise.reject(error)
+    this.deletePromise(id)
+  }
+
+  /**
+   * Reject all pending requests.
+   *
+   * @param error - Error to throw with the reject.
+   */
+  public rejectAll(error: Error): void {
+    this.promisesAwaitingResponse.forEach((_promise, id, _map) => {
+      this.reject(id, error)
+      this.deletePromise(id)
+    })
+  }
+
+  /**
+   * Creates a new WebSocket request. This sets up a timeout timer to catch
+   * hung responses, and a promise that will resolve with the response once
+   * the response is seen & handled.
+   *
+   * @param request - Request to create.
+   * @param timeout - Timeout length to catch hung responses.
+   * @returns Request ID, new request form, and the promise for resolving the request.
+   * @throws XrplError if request with the same ID is already pending.
+   */
+  public createRequest<T extends BaseRequest>(
+    request: T,
+    timeout: number,
+  ): [string | number, string, Promise<Response>] {
+    let newId: string | number
+    if (request.id == null) {
+      newId = this.nextId
+      this.nextId += 1
+    } else {
+      newId = request.id
+    }
+    const newRequest = JSON.stringify({ ...request, id: newId })
+    // Typing required for Jest running in browser
+    const timer: ReturnType<typeof setTimeout> = setTimeout(() => {
+      this.reject(
+        newId,
+        new TimeoutError(
+          `Timeout for request: ${JSON.stringify(request)} with id ${newId}`,
+          request,
+        ),
+      )
+    }, timeout)
+    /*
+     * Node.js won't exit if a timer is still running, so we tell Node to ignore.
+     * (Node will still wait for the request to complete).
+     */
+    // The following type assertions are required to get this code to pass in browser environments
+    // where setTimeout has a different type
+    // eslint-disable-next-line max-len -- Necessary to disable both rules.
+    // eslint-disable-next-line @typescript-eslint/consistent-type-assertions, @typescript-eslint/no-explicit-any, @typescript-eslint/no-unsafe-member-access -- Reason above.
+    if ((timer as unknown as any).unref) {
+      // eslint-disable-next-line max-len -- Necessary to disable both rules.
+      // eslint-disable-next-line @typescript-eslint/consistent-type-assertions, @typescript-eslint/no-explicit-any, @typescript-eslint/no-unsafe-member-access, @typescript-eslint/no-unsafe-call -- Reason above.
+      ;(timer as unknown as any).unref()
+    }
+    if (this.promisesAwaitingResponse.has(newId)) {
+      clearTimeout(timer)
+      throw new XrplError(
+        `Response with id '${newId}' is already pending`,
+        request,
+      )
+    }
+    const newPromise = new Promise<Response>(
+      (resolve: (value: Response | PromiseLike<Response>) => void, reject) => {
+        this.promisesAwaitingResponse.set(newId, { resolve, reject, timer })
+      },
+    )
+
+    return [newId, newRequest, newPromise]
+  }
+
+  /**
+   * Handle a "response". Responses match to the earlier request handlers,
+   * and resolve/reject based on the data received.
+   *
+   * @param response - The response to handle.
+   * @throws ResponseFormatError if the response format is invalid, RippledError if rippled returns an error.
+   */
+  public handleResponse(response: Partial<Response | ErrorResponse>): void {
+    if (
+      response.id == null ||
+      !(typeof response.id === 'string' || typeof response.id === 'number')
+    ) {
+      throw new ResponseFormatError('valid id not found in response', response)
+    }
+    if (!this.promisesAwaitingResponse.has(response.id)) {
+      return
+    }
+    if (response.status == null) {
+      const error = new ResponseFormatError('Response has no status')
+      this.reject(response.id, error)
+    }
+    if (response.status === 'error') {
+      // eslint-disable-next-line @typescript-eslint/consistent-type-assertions -- We know this must be true
+      const errorResponse = response as Partial<ErrorResponse>
+      const error = new RippledError(
+        errorResponse.error_message ?? errorResponse.error,
+        errorResponse,
+      )
+      this.reject(response.id, error)
+      return
+    }
+    if (response.status !== 'success') {
+      const error = new ResponseFormatError(
+        `unrecognized response.status: ${response.status ?? ''}`,
+        response,
+      )
+      this.reject(response.id, error)
+      return
+    }
+    // status no longer needed because error is thrown if status is not "success"
+    delete response.status
+    // eslint-disable-next-line @typescript-eslint/consistent-type-assertions -- Must be a valid Response here
+    this.resolve(response.id, response as unknown as Response)
+  }
+
+  /**
+   * Delete a promise after it has been returned.
+   *
+   * @param id - ID of the request.
+   */
+  private deletePromise(id: string | number): void {
+    this.promisesAwaitingResponse.delete(id)
+  }
+}

package/src/client/WSWrapper.ts

@@ -0,0 +1,106 @@
+/* eslint-disable max-classes-per-file -- Needs to be a wrapper for ws */
+import { EventEmitter } from 'events'
+
+// Define the global WebSocket class found on the native browser
+declare class WebSocket {
+  public onclose?: (closeEvent: CloseEvent) => void
+  public onopen?: (openEvent: Event) => void
+  public onerror?: (error: Error) => void
+  public onmessage?: (message: MessageEvent) => void
+  public readyState: number
+  public constructor(url: string)
+  public close(code?: number, reason?: Buffer): void
+  public send(message: string): void
+}
+
+interface WSWrapperOptions {
+  perMessageDeflate: boolean
+  handshakeTimeout: number
+  protocolVersion: number
+  origin: string
+  maxPayload: number
+  followRedirects: boolean
+  maxRedirects: number
+}
+
+/**
+ * Provides `EventEmitter` interface for native browser `WebSocket`,
+ * same, as `ws` package provides.
+ */
+export default class WSWrapper extends EventEmitter {
+  public static CONNECTING = 0
+  public static OPEN = 1
+  public static CLOSING = 2
+  // eslint-disable-next-line @typescript-eslint/no-magic-numbers -- magic number is being defined here
+  public static CLOSED = 3
+  private readonly ws: WebSocket
+
+  /**
+   * Constructs a browser-safe websocket.
+   *
+   * @param url - URL to connect to.
+   * @param _protocols - Not used.
+   * @param _websocketOptions - Not used.
+   */
+  public constructor(
+    url: string,
+    _protocols: string | string[] | WSWrapperOptions | undefined,
+    _websocketOptions: WSWrapperOptions,
+  ) {
+    super()
+    this.setMaxListeners(Infinity)
+
+    this.ws = new WebSocket(url)
+
+    this.ws.onclose = (closeEvent: CloseEvent): void => {
+      let reason: Uint8Array | undefined
+      if (closeEvent.reason) {
+        const enc = new TextEncoder()
+        reason = enc.encode(closeEvent.reason)
+      }
+      this.emit('close', closeEvent.code, reason)
+    }
+
+    this.ws.onopen = (): void => {
+      this.emit('open')
+    }
+
+    this.ws.onerror = (error): void => {
+      this.emit('error', error)
+    }
+
+    this.ws.onmessage = (message: MessageEvent): void => {
+      this.emit('message', message.data)
+    }
+  }
+
+  /**
+   * Get the ready state of the websocket.
+   *
+   * @returns The Websocket's ready state.
+   */
+  public get readyState(): number {
+    return this.ws.readyState
+  }
+
+  /**
+   * Closes the websocket.
+   *
+   * @param code - Close code.
+   * @param reason - Close reason.
+   */
+  public close(code?: number, reason?: Buffer): void {
+    if (this.readyState === 1) {
+      this.ws.close(code, reason)
+    }
+  }
+
+  /**
+   * Sends a message over the Websocket connection.
+   *
+   * @param message - Message to send.
+   */
+  public send(message: string): void {
+    this.ws.send(message)
+  }
+}