@rc-ex/ws 1.2.2 → 1.3.1

package/lib/index.ts

@@ -1,418 +0,0 @@
-import type RingCentral from "@rc-ex/core";
-import type {
-  RestMethod,
-  RestRequestConfig,
-  RestResponse,
-} from "@rc-ex/core/src/types";
-import SdkExtension from "@rc-ex/core/src/SdkExtension";
-import type { MessageEvent } from "isomorphic-ws";
-import WS from "isomorphic-ws";
-import hyperid from "hyperid";
-import { EventEmitter } from "events";
-import waitFor from "wait-for-async";
-import RestException from "@rc-ex/core/src/RestException";
-import type SubscriptionInfo from "@rc-ex/core/src/definitions/SubscriptionInfo";
-
-import { request } from "./rest";
-import type {
-  ConnectionDetails,
-  WebSocketExtensionInterface,
-  WebSocketOptions,
-  Wsc,
-  WsgEvent,
-  WsToken,
-} from "./types";
-import Subscription from "./subscription";
-import ConnectionException from "./exceptions/ConnectionException";
-import Utils from "./utils";
-
-const CONNECTING = 0;
-const OPEN = 1;
-
-const uuid = hyperid();
-
-export enum Events {
-  autoRecoverSuccess = "autoRecoverSuccess",
-  autoRecoverFailed = "autoRecoverFailed",
-  autoRecoverError = "autoRecoverError",
-  newWebSocketObject = "newWebSocketObject",
-  newWsc = "newWsc",
-  connectionReady = "connectionReady",
-}
-
-class WebSocketExtension extends SdkExtension {
-  public eventEmitter = new EventEmitter();
-
-  public options: WebSocketOptions;
-
-  public rc!: RingCentral;
-
-  public wsToken?: WsToken;
-
-  public wsTokenExpiresAt = 0;
-
-  public ws!: WS;
-
-  public connectionDetails!: ConnectionDetails;
-
-  public wsc?: Wsc;
-
-  public subscription?: Subscription;
-
-  // for auto recover
-  public intervalHandle?: NodeJS.Timeout;
-
-  public recoverTimestamp?: number;
-
-  public pingServerHandle?: NodeJS.Timeout;
-
-  public _recoverPromise?: Promise<void>;
-
-  public _connectPromise?: Promise<void>;
-
-  public request = request; // request method was moved to another file to keep this file short
-
-  public constructor(options: WebSocketOptions = {}) {
-    super();
-    this.options = options;
-    this.options.restOverWebSocket ??= false;
-    this.options.debugMode ??= false;
-    this.options.autoRecover ??= {
-      enabled: true,
-    };
-    this.options.autoRecover.checkInterval ??= (retriesAttempted) => {
-      const interval = 2000 + 2000 * retriesAttempted;
-      return Math.min(8000, interval);
-    };
-    this.options.autoRecover.pingServerInterval ??= 60000;
-  }
-
-  public disable() {
-    super.disable();
-    if (this.subscription) {
-      this.subscription.enabled = false;
-    }
-  }
-
-  public async install(rc: RingCentral) {
-    this.rc = rc;
-    if (this.options.restOverWebSocket) {
-      const request = rc.request.bind(rc);
-      rc.request = async <T>(
-        method: RestMethod,
-        endpoint: string,
-        content?: {},
-        queryParams?: {},
-        config?: RestRequestConfig,
-      ): Promise<RestResponse<T>> => {
-        if (!this.enabled || !this.options.restOverWebSocket) {
-          return request(method, endpoint, content, queryParams, config);
-        }
-        if (
-          // the following cannot be done with WebSocket
-          config?.headers?.getContentType?.toString()?.includes(
-            "multipart/form-data",
-          ) ||
-          config?.responseType === "arraybuffer" ||
-          endpoint.startsWith("/restapi/oauth/") // token, revoke, wstoken
-        ) {
-          return request(method, endpoint, content, queryParams, config);
-        }
-        return this.request<T>(method, endpoint, content, queryParams, config);
-      };
-    }
-
-    // should recover if this.options.wscToken
-    let connectMethod = this.connect.bind(this);
-    if (this.options.wscToken) {
-      this.wsc = {
-        token: this.options.wscToken,
-        sequence: 0,
-      };
-      connectMethod = this.recover.bind(this);
-    }
-
-    if (!this.options.autoRecover!.enabled) {
-      await connectMethod();
-      return;
-    }
-
-    // code after is for auto recover
-    try {
-      await connectMethod();
-    } catch (e) {
-      if (e instanceof RestException) {
-        throw e; // such as InsufficientPermissions
-      }
-      if (this.options.debugMode) {
-        console.debug("Initial connect failed:", e);
-      }
-    }
-    let retriesAttempted = 0;
-    let checking = false;
-    const check = async () => {
-      if (!this.enabled) {
-        return;
-      }
-      if (this.options.autoRecover?.enabled !== true) {
-        return;
-      }
-      if (checking) {
-        return;
-      }
-      checking = true;
-      if (this.ws?.readyState !== OPEN && this.ws?.readyState !== CONNECTING) {
-        clearInterval(this.intervalHandle!);
-        try {
-          await this.recover();
-          retriesAttempted = 0;
-          if (this.options.debugMode) {
-            console.debug(
-              `Auto recover done, recoveryState: ${this.connectionDetails.recoveryState}`,
-            );
-          }
-          this.eventEmitter.emit(
-            this.connectionDetails.recoveryState === "Successful"
-              ? Events.autoRecoverSuccess
-              : Events.autoRecoverFailed,
-            this.ws,
-          );
-        } catch (e) {
-          if (e instanceof RestException) {
-            throw e; // such as InsufficientPermissions
-          }
-          retriesAttempted += 1;
-          if (this.options.debugMode) {
-            console.debug("Auto recover error:", e);
-          }
-          this.eventEmitter.emit(Events.autoRecoverError, e);
-        }
-        this.intervalHandle = setInterval(
-          check,
-          this.options.autoRecover!.checkInterval!(retriesAttempted),
-        );
-      }
-      checking = false;
-    };
-    this.intervalHandle = setInterval(
-      check,
-      this.options.autoRecover!.checkInterval!(retriesAttempted),
-    );
-
-    // browser only code start
-    if (typeof window !== "undefined" && window.addEventListener) {
-      window.addEventListener("offline", () => {
-        if (this.pingServerHandle) {
-          clearTimeout(this.pingServerHandle);
-        }
-        this.ws?.close();
-      });
-      window.addEventListener("online", () => {
-        check();
-      });
-    }
-    // browser only code end
-  }
-
-  public async recover() {
-    if (this._recoverPromise) {
-      return this._recoverPromise;
-    }
-    this._recoverPromise = this._recover();
-    try {
-      await this._recoverPromise;
-    } finally {
-      this._recoverPromise = undefined;
-    }
-    return undefined;
-  }
-
-  public async _recover() {
-    if (this.ws?.readyState === OPEN || this.ws?.readyState === CONNECTING) {
-      return;
-    }
-    if (!this.wsc || !this.wsc.token) {
-      await this.connect(false); // connect to WSG but do not recover
-      return;
-    }
-    if (this.recoverTimestamp === undefined) {
-      this.recoverTimestamp = Date.now();
-    }
-    if (
-      this.connectionDetails !== undefined &&
-      Date.now() - this.recoverTimestamp >
-        this.connectionDetails.recoveryTimeout * 1000
-    ) {
-      if (this.options.debugMode) {
-        console.debug("connect to WSG but do not recover");
-      }
-      await this.connect(false); // connect to WSG but do not recover
-    } else {
-      if (this.options.debugMode) {
-        console.debug("connect to WSG and recover");
-      }
-      await this.connect(true); // connect to WSG and recover
-    }
-    this.recoverTimestamp = undefined;
-    this.enable();
-  }
-
-  public async pingServer() {
-    if (this.options.autoRecover?.enabled !== true) {
-      return;
-    }
-    if (this.ws?.readyState !== OPEN) {
-      return;
-    }
-    try {
-      await this.ws.send(
-        JSON.stringify([
-          {
-            type: "Heartbeat",
-            messageId: uuid(),
-          },
-        ]),
-      );
-    } catch (e) {
-      this.ws.close(); // Explicitly mark WS as closed
-    }
-  }
-
-  public async connect(recoverSession?: boolean) {
-    if (this._connectPromise) {
-      return this._connectPromise;
-    }
-    this._connectPromise = this._connect(recoverSession);
-    try {
-      await this._connectPromise;
-    } finally {
-      this._connectPromise = undefined;
-    }
-    return undefined;
-  }
-
-  public async _connect(recoverSession = false) {
-    if (!this.wsToken || Date.now() > this.wsTokenExpiresAt) {
-      const r = await this.rc.post("/restapi/oauth/wstoken");
-      this.wsToken = r.data as WsToken;
-      // `expires_in` default value is 600 seconds. That's why we `* 0.8`
-      this.wsTokenExpiresAt = Date.now() + this.wsToken.expires_in * 0.8 * 1000;
-    }
-    let wsUri = `${this.wsToken!.uri}?access_token=${
-      this.wsToken!.ws_access_token
-    }`;
-    if (recoverSession && this.wsc) {
-      wsUri += `&wsc=${this.wsc.token}`;
-    }
-    this.ws = new WS(wsUri);
-    this.eventEmitter.emit(Events.newWebSocketObject, this.ws);
-
-    // override send method to wait for connecting
-    const send = this.ws.send.bind(this.ws);
-    this.ws.send = async (s: string) => {
-      if (this.ws.readyState === CONNECTING) {
-        await waitFor({
-          interval: 100,
-          condition: () => this.ws.readyState !== CONNECTING,
-        });
-      }
-      await send(s);
-    };
-
-    if (this.options.autoRecover?.enabled) {
-      this.ws.addEventListener("message", () => {
-        if (this.pingServerHandle) {
-          clearTimeout(this.pingServerHandle);
-        }
-        this.pingServerHandle = setTimeout(
-          () => this.pingServer(),
-          this.options.autoRecover!.pingServerInterval,
-        );
-      });
-    }
-
-    // debug mode to print all WebSocket traffic
-    if (this.options.debugMode) {
-      Utils.debugWebSocket(this.ws);
-    }
-
-    // listen for new wsc data
-    this.ws.addEventListener("message", (mEvent: MessageEvent) => {
-      const event = mEvent as WsgEvent;
-      const [meta, body] = Utils.splitWsgData(event.data);
-      if (
-        meta.wsc &&
-        (!this.wsc ||
-          (meta.type === "ConnectionDetails" && body.recoveryState) ||
-          this.wsc.sequence < meta.wsc.sequence)
-      ) {
-        this.wsc = meta.wsc;
-        this.eventEmitter.emit(Events.newWsc, this.wsc);
-      }
-    });
-
-    // get initial ConnectionDetails data
-    const [meta, body, event] = await Utils.waitForWebSocketMessage(
-      this.ws,
-      (meta) => meta.type === "ConnectionDetails" || meta.type === "Error",
-    );
-    if (meta.type === "Error") {
-      throw new ConnectionException(event);
-    }
-    this.connectionDetails = body;
-
-    // fired when ws connection is ready for creating subscription
-    this.eventEmitter.emit(Events.connectionReady, this.ws);
-
-    // recover the subscription, if it exists and enabled
-    if (this.subscription && this.subscription.enabled) {
-      // because we have a new ws object
-      this.subscription.setupWsEventListener();
-      if (
-        !recoverSession || this.connectionDetails.recoveryState === "Failed"
-      ) {
-        // create new subscription if don't recover existing one
-        await this.subscription.subscribe();
-      }
-    }
-  }
-
-  // keepInterval means we do not clear the interval
-  public async revoke(keepInterval = false) {
-    await this.subscription?.revoke();
-    this.subscription = undefined;
-    if (!keepInterval && this.intervalHandle) {
-      clearInterval(this.intervalHandle);
-    }
-    if (this.pingServerHandle) {
-      clearTimeout(this.pingServerHandle);
-    }
-    this.ws?.close();
-    this.wsc = undefined;
-    this.wsToken = undefined;
-    this.wsTokenExpiresAt = 0;
-    this.disable();
-  }
-
-  public async subscribe(
-    eventFilters: string[],
-    callback: (event: {}) => void,
-    cache: SubscriptionInfo | undefined | null = undefined,
-  ) {
-    const subscription = new Subscription(
-      this as WebSocketExtensionInterface,
-      eventFilters,
-      callback,
-    );
-    if (cache === undefined || cache === null) {
-      await subscription.subscribe();
-    } else {
-      subscription.subscriptionInfo = cache;
-      await subscription.refresh();
-    }
-    this.subscription = subscription;
-    return subscription;
-  }
-}
-
-export default WebSocketExtension;

package/lib/rest.ts

@@ -1,71 +0,0 @@
-import type {
-  RestMethod,
-  RestRequestConfig,
-  RestResponse,
-} from "@rc-ex/core/src/types";
-import RestException from "@rc-ex/core/src/RestException";
-import hyperid from "hyperid";
-import { getReasonPhrase } from "http-status-codes";
-
-import Utils from "./utils";
-import type { WebSocketExtensionInterface } from "./types";
-
-const version = "0.16";
-
-const uuid = hyperid();
-
-export async function request<T>(
-  this: WebSocketExtensionInterface,
-  method: RestMethod,
-  endpoint: string,
-  content?: {},
-  queryParams?: {},
-  config?: RestRequestConfig,
-): Promise<RestResponse<T>> {
-  const newConfig: RestRequestConfig = {
-    method,
-    baseURL: this.wsToken?.uri,
-    url: endpoint,
-    data: content,
-    params: queryParams,
-    ...config,
-  };
-  newConfig.headers = {
-    ...newConfig.headers,
-    "X-User-Agent": `${this.rc.rest!.appName}/${
-      this.rc.rest!.appVersion
-    } ringcentral-extensible/ws/${version}`,
-  } as any;
-  const messageId = uuid();
-  const requestBody = [
-    {
-      type: "ClientRequest",
-      messageId,
-      method: newConfig.method,
-      path: newConfig.url,
-      headers: newConfig.headers,
-      query: newConfig.params,
-    },
-  ];
-  if (newConfig.data) {
-    requestBody.push(newConfig.data);
-  }
-  await this.ws.send(JSON.stringify(requestBody));
-  const [meta, body] = await Utils.waitForWebSocketMessage(
-    this.ws,
-    (_meta) => _meta.messageId === messageId,
-  );
-  const response: RestResponse = {
-    data: body as T,
-    status: meta.status,
-    statusText: getReasonPhrase(meta.status),
-    headers: meta.headers,
-    config: newConfig as any,
-  };
-  if (
-    meta.type === "ClientRequest" && meta.status >= 200 && meta.status < 300
-  ) {
-    return response;
-  }
-  throw new RestException(response);
-}

package/lib/subscription.ts

@@ -1,131 +0,0 @@
-import type CreateSubscriptionRequest from "@rc-ex/core/src/definitions/CreateSubscriptionRequest";
-import type SubscriptionInfo from "@rc-ex/core/src/definitions/SubscriptionInfo";
-import type { RestResponse } from "@rc-ex/core/src/types";
-import type { MessageEvent } from "ws";
-
-import type { WebSocketExtensionInterface, WsgEvent, WsgMeta } from "./types";
-import Utils from "./utils";
-
-class Subscription {
-  public subscriptionInfo?: SubscriptionInfo;
-
-  public wse: WebSocketExtensionInterface;
-
-  public eventFilters: string[];
-
-  public eventListener: (event: MessageEvent) => void;
-
-  public timeout?: NodeJS.Timeout;
-
-  public enabled = true;
-
-  public constructor(
-    wse: WebSocketExtensionInterface,
-    eventFilters: string[],
-    callback: (event: {}) => void,
-  ) {
-    this.wse = wse;
-    this.eventFilters = eventFilters;
-    this.eventListener = (mEvent: MessageEvent) => {
-      const event = mEvent as WsgEvent;
-      const [meta, body]: [WsgMeta, { subscriptionId: string }] = Utils
-        .splitWsgData(event.data);
-      if (
-        this.enabled && meta.type === "ServerNotification" &&
-        body.subscriptionId === this.subscriptionInfo!.id
-      ) {
-        callback(body);
-      }
-    };
-    this.setupWsEventListener();
-  }
-
-  public setupWsEventListener() {
-    this.wse.ws.addEventListener("message", this.eventListener);
-  }
-
-  public get requestBody(): CreateSubscriptionRequest {
-    return {
-      deliveryMode: { transportType: "WebSocket" as any }, // because WebSocket is not in spec
-      eventFilters: this.eventFilters,
-    };
-  }
-
-  public async subscribe() {
-    this.subscriptionInfo = (
-      await this.wse.request<SubscriptionInfo>(
-        "POST",
-        "/restapi/v1.0/subscription",
-        this.requestBody,
-      )
-    ).data;
-  }
-
-  public async refresh() {
-    if (!this.subscriptionInfo) {
-      return;
-    }
-    try {
-      this.subscriptionInfo = (
-        await this.wse.request<SubscriptionInfo>(
-          "PUT",
-          `/restapi/v1.0/subscription/${this.subscriptionInfo!.id}`,
-          this.requestBody,
-        )
-      ).data;
-    } catch (e) {
-      const re = e as { response: RestResponse };
-      if (re.response && re.response.status === 404) {
-        // subscription expired
-        await this.subscribe();
-      }
-    }
-  }
-
-  public async revoke() {
-    if (!this.subscriptionInfo) {
-      return;
-    }
-    try {
-      await this.wse.request<SubscriptionInfo>(
-        "DELETE",
-        `/restapi/v1.0/subscription/${this.subscriptionInfo!.id}`,
-      );
-    } catch (e) {
-      const re = e as { response: RestResponse };
-      if (re.response && re.response.status === 404) {
-        // ignore
-        if (this.wse.options.debugMode) {
-          console.debug(
-            `Subscription ${
-              this.subscriptionInfo!.id
-            } doesn't exist on server side`,
-          );
-        }
-      } else if (re.response && re.response.status === 401) {
-        // ignore
-        if (this.wse.options.debugMode) {
-          console.debug("Token invalid when trying to revoke subscription");
-        }
-      } else {
-        throw e;
-      }
-    }
-    this.remove();
-  }
-
-  public remove() {
-    if (this.timeout) {
-      global.clearTimeout(this.timeout);
-      this.timeout = undefined;
-    }
-    this.enabled = false;
-    this.subscriptionInfo = undefined;
-    if (this.wse.ws) {
-      this.wse.ws.removeEventListener("message", this.eventListener);
-    }
-    this.wse.subscription = undefined;
-  }
-}
-
-export default Subscription;

package/lib/types.ts

@@ -1,85 +0,0 @@
-import type RingCentral from "@rc-ex/core";
-import type {
-  RestMethod,
-  RestRequestConfig,
-  RestResponse,
-} from "@rc-ex/core/src/types";
-import type WS from "isomorphic-ws";
-
-export interface WsToken {
-  uri: string;
-  ws_access_token: string;
-  expires_in: number;
-}
-
-export type CheckInterval = (retriesAttempted: number) => number;
-export interface WebSocketOptions {
-  restOverWebSocket?: boolean;
-  debugMode?: boolean;
-  autoRecover?: {
-    enabled: boolean;
-    checkInterval?: CheckInterval;
-    pingServerInterval?: number;
-  };
-  wscToken?: string;
-}
-
-export interface WsgEvent {
-  data: string;
-}
-
-export interface Wsc {
-  token: string;
-  sequence: number;
-}
-
-export interface WsgMeta {
-  type:
-    | "ClientRequest"
-    | "ServerNotification"
-    | "Error"
-    | "ConnectionDetails"
-    | "Heartbeat";
-  messageId: string;
-  status: number;
-  headers: {
-    [key: string]: string;
-  };
-  wsc?: Wsc;
-}
-
-export interface WsgError {
-  errorCode: string;
-  message: string;
-}
-
-export interface ConnectionDetails {
-  creationTime: string;
-  maxConnectionsPerSession: number;
-  recoveryBufferSize: number;
-  recoveryTimeout: number;
-  idleTimeout: number;
-  absoluteTimeout: number;
-  maxActiveRequests: number;
-  recoveryState?: "Successful" | "Failed";
-  recoveryErrorCode?: string;
-}
-
-export interface WebSocketExtensionInterface {
-  options: WebSocketOptions;
-  subscription?: SubscriptionInterface;
-  ws: WS;
-  wsToken?: WsToken;
-  rc: RingCentral;
-  request: <T>(
-    method: RestMethod,
-    endpoint: string,
-    content?: {},
-    queryParams?: {},
-    config?: RestRequestConfig,
-  ) => Promise<RestResponse<T>>;
-}
-
-export interface SubscriptionInterface {
-  eventFilters: string[];
-}