@stomp/stompjs 6.1.1 → 7.0.0-beta1

package/src/compatibility/compat-client.ts

@@ -0,0 +1,269 @@
+import { Client } from '../client';
+import { StompHeaders } from '../stomp-headers';
+import { frameCallbackType, messageCallbackType } from '../types';
+import { HeartbeatInfo } from './heartbeat-info';
+
+/**
+ * Available for backward compatibility, please shift to using {@link Client}.
+ *
+ * **Deprecated**
+ *
+ * Part of `@stomp/stompjs`.
+ *
+ * To upgrade, please follow the [Upgrade Guide](../additional-documentation/upgrading.html)
+ */
+export class CompatClient extends Client {
+  /**
+   * It is no op now. No longer needed. Large packets work out of the box.
+   */
+  public maxWebSocketFrameSize: number = 16 * 1024;
+
+  /**
+   * Available for backward compatibility, please shift to using {@link Client}
+   * and [Client#webSocketFactory]{@link Client#webSocketFactory}.
+   *
+   * **Deprecated**
+   *
+   * @internal
+   */
+  constructor(webSocketFactory: () => any) {
+    super();
+    this.reconnect_delay = 0;
+    this.webSocketFactory = webSocketFactory;
+    // Default from previous version
+    this.debug = (...message: any[]) => {
+      console.log(...message);
+    };
+  }
+
+  private _parseConnect(...args: any[]): any {
+    let closeEventCallback;
+    let connectCallback;
+    let errorCallback;
+    let headers: StompHeaders = {};
+    if (args.length < 2) {
+      throw new Error('Connect requires at least 2 arguments');
+    }
+    if (typeof args[1] === 'function') {
+      [headers, connectCallback, errorCallback, closeEventCallback] = args;
+    } else {
+      switch (args.length) {
+        case 6:
+          [
+            headers.login,
+            headers.passcode,
+            connectCallback,
+            errorCallback,
+            closeEventCallback,
+            headers.host,
+          ] = args;
+          break;
+        default:
+          [
+            headers.login,
+            headers.passcode,
+            connectCallback,
+            errorCallback,
+            closeEventCallback,
+          ] = args;
+      }
+    }
+
+    return [headers, connectCallback, errorCallback, closeEventCallback];
+  }
+
+  /**
+   * Available for backward compatibility, please shift to using [Client#activate]{@link Client#activate}.
+   *
+   * **Deprecated**
+   *
+   * The `connect` method accepts different number of arguments and types. See the Overloads list. Use the
+   * version with headers to pass your broker specific options.
+   *
+   * overloads:
+   * - connect(headers, connectCallback)
+   * - connect(headers, connectCallback, errorCallback)
+   * - connect(login, passcode, connectCallback)
+   * - connect(login, passcode, connectCallback, errorCallback)
+   * - connect(login, passcode, connectCallback, errorCallback, closeEventCallback)
+   * - connect(login, passcode, connectCallback, errorCallback, closeEventCallback, host)
+   *
+   * params:
+   * - headers, see [Client#connectHeaders]{@link Client#connectHeaders}
+   * - connectCallback, see [Client#onConnect]{@link Client#onConnect}
+   * - errorCallback, see [Client#onStompError]{@link Client#onStompError}
+   * - closeEventCallback, see [Client#onWebSocketClose]{@link Client#onWebSocketClose}
+   * - login [String], see [Client#connectHeaders](../classes/Client.html#connectHeaders)
+   * - passcode [String], [Client#connectHeaders](../classes/Client.html#connectHeaders)
+   * - host [String], see [Client#connectHeaders](../classes/Client.html#connectHeaders)
+   *
+   * To upgrade, please follow the [Upgrade Guide](../additional-documentation/upgrading.html)
+   */
+  public connect(...args: any[]): void {
+    const out = this._parseConnect(...args);
+
+    if (out[0]) {
+      this.connectHeaders = out[0];
+    }
+    if (out[1]) {
+      this.onConnect = out[1];
+    }
+    if (out[2]) {
+      this.onStompError = out[2];
+    }
+    if (out[3]) {
+      this.onWebSocketClose = out[3];
+    }
+
+    super.activate();
+  }
+
+  /**
+   * Available for backward compatibility, please shift to using [Client#deactivate]{@link Client#deactivate}.
+   *
+   * **Deprecated**
+   *
+   * See:
+   * [Client#onDisconnect]{@link Client#onDisconnect}, and
+   * [Client#disconnectHeaders]{@link Client#disconnectHeaders}
+   *
+   * To upgrade, please follow the [Upgrade Guide](../additional-documentation/upgrading.html)
+   */
+  public disconnect(
+    disconnectCallback?: any,
+    headers: StompHeaders = {}
+  ): void {
+    if (disconnectCallback) {
+      this.onDisconnect = disconnectCallback;
+    }
+    this.disconnectHeaders = headers;
+
+    super.deactivate();
+  }
+
+  /**
+   * Available for backward compatibility, use [Client#publish]{@link Client#publish}.
+   *
+   * Send a message to a named destination. Refer to your STOMP broker documentation for types
+   * and naming of destinations. The headers will, typically, be available to the subscriber.
+   * However, there may be special purpose headers corresponding to your STOMP broker.
+   *
+   *  **Deprecated**, use [Client#publish]{@link Client#publish}
+   *
+   * Note: Body must be String. You will need to covert the payload to string in case it is not string (e.g. JSON)
+   *
+   * ```javascript
+   *        client.send("/queue/test", {priority: 9}, "Hello, STOMP");
+   *
+   *        // If you want to send a message with a body, you must also pass the headers argument.
+   *        client.send("/queue/test", {}, "Hello, STOMP");
+   * ```
+   *
+   * To upgrade, please follow the [Upgrade Guide](../additional-documentation/upgrading.html)
+   */
+  public send(
+    destination: string,
+    headers: { [key: string]: any } = {},
+    body: string = ''
+  ): void {
+    headers = (Object as any).assign({}, headers);
+
+    const skipContentLengthHeader = headers['content-length'] === false;
+    if (skipContentLengthHeader) {
+      delete headers['content-length'];
+    }
+    this.publish({
+      destination,
+      headers: headers as StompHeaders,
+      body,
+      skipContentLengthHeader,
+    });
+  }
+
+  /**
+   * Available for backward compatibility, renamed to [Client#reconnectDelay]{@link Client#reconnectDelay}.
+   *
+   * **Deprecated**
+   */
+  set reconnect_delay(value: number) {
+    this.reconnectDelay = value;
+  }
+
+  /**
+   * Available for backward compatibility, renamed to [Client#webSocket]{@link Client#webSocket}.
+   *
+   * **Deprecated**
+   */
+  get ws(): any {
+    return this.webSocket;
+  }
+
+  /**
+   * Available for backward compatibility, renamed to [Client#connectedVersion]{@link Client#connectedVersion}.
+   *
+   * **Deprecated**
+   */
+  get version() {
+    return this.connectedVersion;
+  }
+
+  /**
+   * Available for backward compatibility, renamed to [Client#onUnhandledMessage]{@link Client#onUnhandledMessage}.
+   *
+   * **Deprecated**
+   */
+  get onreceive(): messageCallbackType {
+    return this.onUnhandledMessage;
+  }
+
+  /**
+   * Available for backward compatibility, renamed to [Client#onUnhandledMessage]{@link Client#onUnhandledMessage}.
+   *
+   * **Deprecated**
+   */
+  set onreceive(value: messageCallbackType) {
+    this.onUnhandledMessage = value;
+  }
+
+  /**
+   * Available for backward compatibility, renamed to [Client#onUnhandledReceipt]{@link Client#onUnhandledReceipt}.
+   * Prefer using [Client#watchForReceipt]{@link Client#watchForReceipt}.
+   *
+   * **Deprecated**
+   */
+  get onreceipt(): frameCallbackType {
+    return this.onUnhandledReceipt;
+  }
+
+  /**
+   * Available for backward compatibility, renamed to [Client#onUnhandledReceipt]{@link Client#onUnhandledReceipt}.
+   *
+   * **Deprecated**
+   */
+  set onreceipt(value: frameCallbackType) {
+    this.onUnhandledReceipt = value;
+  }
+
+  private _heartbeatInfo: HeartbeatInfo = new HeartbeatInfo(this);
+
+  /**
+   * Available for backward compatibility, renamed to [Client#heartbeatIncoming]{@link Client#heartbeatIncoming}
+   * [Client#heartbeatOutgoing]{@link Client#heartbeatOutgoing}.
+   *
+   * **Deprecated**
+   */
+  get heartbeat() {
+    return this._heartbeatInfo;
+  }
+
+  /**
+   * Available for backward compatibility, renamed to [Client#heartbeatIncoming]{@link Client#heartbeatIncoming}
+   * [Client#heartbeatOutgoing]{@link Client#heartbeatOutgoing}.
+   *
+   * **Deprecated**
+   */
+  set heartbeat(value: { incoming: number; outgoing: number }) {
+    this.heartbeatIncoming = value.incoming;
+    this.heartbeatOutgoing = value.outgoing;
+  }
+}

package/src/compatibility/heartbeat-info.ts

@@ -0,0 +1,26 @@
+import { CompatClient } from './compat-client';
+
+/**
+ * Part of `@stomp/stompjs`.
+ *
+ * @internal
+ */
+export class HeartbeatInfo {
+  constructor(private client: CompatClient) {}
+
+  get outgoing(): number {
+    return this.client.heartbeatOutgoing;
+  }
+
+  set outgoing(value: number) {
+    this.client.heartbeatOutgoing = value;
+  }
+
+  get incoming(): number {
+    return this.client.heartbeatIncoming;
+  }
+
+  set incoming(value: number) {
+    this.client.heartbeatIncoming = value;
+  }
+}

package/src/compatibility/stomp.ts

@@ -0,0 +1,118 @@
+import { Versions } from '../versions';
+import { CompatClient } from './compat-client';
+import { IStompSocket } from '../types';
+
+/**
+ * @internal
+ */
+declare const WebSocket: {
+  prototype: IStompSocket;
+  new (url: string, protocols?: string | string[]): IStompSocket;
+};
+
+/**
+ * STOMP Class, acts like a factory to create {@link Client}.
+ *
+ * Part of `@stomp/stompjs`.
+ *
+ * **Deprecated**
+ *
+ * It will be removed in next major version. Please switch to {@link Client}.
+ */
+export class Stomp {
+  /**
+   * In case you need to use a non standard class for WebSocket.
+   *
+   * For example when using within NodeJS environment:
+   *
+   * ```javascript
+   *        StompJs = require('../../esm5/');
+   *        Stomp = StompJs.Stomp;
+   *        Stomp.WebSocketClass = require('websocket').w3cwebsocket;
+   * ```
+   *
+   * **Deprecated**
+   *
+   *
+   * It will be removed in next major version. Please switch to {@link Client}
+   * using [Client#webSocketFactory]{@link Client#webSocketFactory}.
+   */
+  // tslint:disable-next-line:variable-name
+  public static WebSocketClass: any = null;
+
+  /**
+   * This method creates a WebSocket client that is connected to
+   * the STOMP server located at the url.
+   *
+   * ```javascript
+   *        var url = "ws://localhost:61614/stomp";
+   *        var client = Stomp.client(url);
+   * ```
+   *
+   * **Deprecated**
+   *
+   * It will be removed in next major version. Please switch to {@link Client}
+   * using [Client#brokerURL]{@link Client#brokerURL}.
+   */
+  public static client(url: string, protocols?: string[]): CompatClient {
+    // This is a hack to allow another implementation than the standard
+    // HTML5 WebSocket class.
+    //
+    // It is possible to use another class by calling
+    //
+    //     Stomp.WebSocketClass = MozWebSocket
+    //
+    // *prior* to call `Stomp.client()`.
+    //
+    // This hack is deprecated and `Stomp.over()` method should be used
+    // instead.
+
+    // See remarks on the function Stomp.over
+    if (protocols == null) {
+      protocols = Versions.default.protocolVersions();
+    }
+    const wsFn = () => {
+      const klass = Stomp.WebSocketClass || WebSocket;
+      return new klass(url, protocols);
+    };
+
+    return new CompatClient(wsFn);
+  }
+
+  /**
+   * This method is an alternative to [Stomp#client]{@link Stomp#client} to let the user
+   * specify the WebSocket to use (either a standard HTML5 WebSocket or
+   * a similar object).
+   *
+   * In order to support reconnection, the function Client._connect should be callable more than once.
+   * While reconnecting
+   * a new instance of underlying transport (TCP Socket, WebSocket or SockJS) will be needed. So, this function
+   * alternatively allows passing a function that should return a new instance of the underlying socket.
+   *
+   * ```javascript
+   *        var client = Stomp.over(function(){
+   *          return new WebSocket('ws://localhost:15674/ws')
+   *        });
+   * ```
+   *
+   * **Deprecated**
+   *
+   * It will be removed in next major version. Please switch to {@link Client}
+   * using [Client#webSocketFactory]{@link Client#webSocketFactory}.
+   */
+  public static over(ws: any): CompatClient {
+    let wsFn: () => any;
+
+    if (typeof ws === 'function') {
+      wsFn = ws;
+    } else {
+      console.warn(
+        'Stomp.over did not receive a factory, auto reconnect will not work. ' +
+          'Please see https://stomp-js.github.io/api-docs/latest/classes/Stomp.html#over'
+      );
+      wsFn = () => ws;
+    }
+
+    return new CompatClient(wsFn);
+  }
+}

package/src/frame-impl.ts

@@ -0,0 +1,254 @@
+import { BYTE } from './byte';
+import { IFrame } from './i-frame';
+import { StompHeaders } from './stomp-headers';
+import { IRawFrameType } from './types';
+
+/**
+ * Frame class represents a STOMP frame.
+ *
+ * @internal
+ */
+export class FrameImpl implements IFrame {
+  /**
+   * STOMP Command
+   */
+  public command: string;
+
+  /**
+   * Headers, key value pairs.
+   */
+  public headers: StompHeaders;
+
+  /**
+   * Is this frame binary (based on whether body/binaryBody was passed when creating this frame).
+   */
+  public isBinaryBody: boolean;
+
+  /**
+   * body of the frame
+   */
+  get body(): string {
+    if (!this._body && this.isBinaryBody) {
+      this._body = new TextDecoder().decode(this._binaryBody);
+    }
+    return this._body || '';
+  }
+  private _body: string | undefined;
+
+  /**
+   * body as Uint8Array
+   */
+  get binaryBody(): Uint8Array {
+    if (!this._binaryBody && !this.isBinaryBody) {
+      this._binaryBody = new TextEncoder().encode(this._body);
+    }
+    // At this stage it will definitely have a valid value
+    return this._binaryBody as Uint8Array;
+  }
+  private _binaryBody: Uint8Array | undefined;
+
+  private escapeHeaderValues: boolean;
+  private skipContentLengthHeader: boolean;
+
+  /**
+   * Frame constructor. `command`, `headers` and `body` are available as properties.
+   *
+   * @internal
+   */
+  constructor(params: {
+    command: string;
+    headers?: StompHeaders;
+    body?: string;
+    binaryBody?: Uint8Array;
+    escapeHeaderValues?: boolean;
+    skipContentLengthHeader?: boolean;
+  }) {
+    const {
+      command,
+      headers,
+      body,
+      binaryBody,
+      escapeHeaderValues,
+      skipContentLengthHeader,
+    } = params;
+    this.command = command;
+    this.headers = (Object as any).assign({}, headers || {});
+
+    if (binaryBody) {
+      this._binaryBody = binaryBody;
+      this.isBinaryBody = true;
+    } else {
+      this._body = body || '';
+      this.isBinaryBody = false;
+    }
+    this.escapeHeaderValues = escapeHeaderValues || false;
+    this.skipContentLengthHeader = skipContentLengthHeader || false;
+  }
+
+  /**
+   * deserialize a STOMP Frame from raw data.
+   *
+   * @internal
+   */
+  public static fromRawFrame(
+    rawFrame: IRawFrameType,
+    escapeHeaderValues: boolean
+  ): FrameImpl {
+    const headers: StompHeaders = {};
+    const trim = (str: string): string => str.replace(/^\s+|\s+$/g, '');
+
+    // In case of repeated headers, as per standards, first value need to be used
+    for (const header of rawFrame.headers.reverse()) {
+      const idx = header.indexOf(':');
+
+      const key = trim(header[0]);
+      let value = trim(header[1]);
+
+      if (
+        escapeHeaderValues &&
+        rawFrame.command !== 'CONNECT' &&
+        rawFrame.command !== 'CONNECTED'
+      ) {
+        value = FrameImpl.hdrValueUnEscape(value);
+      }
+
+      headers[key] = value;
+    }
+
+    return new FrameImpl({
+      command: rawFrame.command as string,
+      headers,
+      binaryBody: rawFrame.binaryBody,
+      escapeHeaderValues,
+    });
+  }
+
+  /**
+   * @internal
+   */
+  public toString(): string {
+    return this.serializeCmdAndHeaders();
+  }
+
+  /**
+   * serialize this Frame in a format suitable to be passed to WebSocket.
+   * If the body is string the output will be string.
+   * If the body is binary (i.e. of type Unit8Array) it will be serialized to ArrayBuffer.
+   *
+   * @internal
+   */
+  public serialize(): string | ArrayBuffer {
+    const cmdAndHeaders = this.serializeCmdAndHeaders();
+
+    if (this.isBinaryBody) {
+      return FrameImpl.toUnit8Array(
+        cmdAndHeaders,
+        this._binaryBody as Uint8Array
+      ).buffer;
+    } else {
+      return cmdAndHeaders + this._body + BYTE.NULL;
+    }
+  }
+
+  private serializeCmdAndHeaders(): string {
+    const lines = [this.command];
+    if (this.skipContentLengthHeader) {
+      delete this.headers['content-length'];
+    }
+
+    for (const name of Object.keys(this.headers || {})) {
+      const value = this.headers[name];
+      if (
+        this.escapeHeaderValues &&
+        this.command !== 'CONNECT' &&
+        this.command !== 'CONNECTED'
+      ) {
+        lines.push(`${name}:${FrameImpl.hdrValueEscape(`${value}`)}`);
+      } else {
+        lines.push(`${name}:${value}`);
+      }
+    }
+    if (
+      this.isBinaryBody ||
+      (!this.isBodyEmpty() && !this.skipContentLengthHeader)
+    ) {
+      lines.push(`content-length:${this.bodyLength()}`);
+    }
+    return lines.join(BYTE.LF) + BYTE.LF + BYTE.LF;
+  }
+
+  private isBodyEmpty(): boolean {
+    return this.bodyLength() === 0;
+  }
+
+  private bodyLength(): number {
+    const binaryBody = this.binaryBody;
+    return binaryBody ? binaryBody.length : 0;
+  }
+
+  /**
+   * Compute the size of a UTF-8 string by counting its number of bytes
+   * (and not the number of characters composing the string)
+   */
+  private static sizeOfUTF8(s: string): number {
+    return s ? new TextEncoder().encode(s).length : 0;
+  }
+
+  private static toUnit8Array(
+    cmdAndHeaders: string,
+    binaryBody: Uint8Array
+  ): Uint8Array {
+    const uint8CmdAndHeaders = new TextEncoder().encode(cmdAndHeaders);
+    const nullTerminator = new Uint8Array([0]);
+    const uint8Frame = new Uint8Array(
+      uint8CmdAndHeaders.length + binaryBody.length + nullTerminator.length
+    );
+
+    uint8Frame.set(uint8CmdAndHeaders);
+    uint8Frame.set(binaryBody, uint8CmdAndHeaders.length);
+    uint8Frame.set(
+      nullTerminator,
+      uint8CmdAndHeaders.length + binaryBody.length
+    );
+
+    return uint8Frame;
+  }
+  /**
+   * Serialize a STOMP frame as per STOMP standards, suitable to be sent to the STOMP broker.
+   *
+   * @internal
+   */
+  public static marshall(params: {
+    command: string;
+    headers?: StompHeaders;
+    body?: string;
+    binaryBody?: Uint8Array;
+    escapeHeaderValues?: boolean;
+    skipContentLengthHeader?: boolean;
+  }) {
+    const frame = new FrameImpl(params);
+    return frame.serialize();
+  }
+
+  /**
+   *  Escape header values
+   */
+  private static hdrValueEscape(str: string): string {
+    return str
+      .replace(/\\/g, '\\\\')
+      .replace(/\r/g, '\\r')
+      .replace(/\n/g, '\\n')
+      .replace(/:/g, '\\c');
+  }
+
+  /**
+   * UnEscape header values
+   */
+  private static hdrValueUnEscape(str: string): string {
+    return str
+      .replace(/\\r/g, '\r')
+      .replace(/\\n/g, '\n')
+      .replace(/\\c/g, ':')
+      .replace(/\\\\/g, '\\');
+  }
+}

package/src/i-frame.ts

@@ -0,0 +1,41 @@
+import { StompHeaders } from './stomp-headers';
+
+/**
+ * It represents a STOMP frame. Many of the callbacks pass an IFrame received from
+ * the STOMP broker. For advanced usage you might need to access [headers]{@link IFrame#headers}.
+ *
+ * Part of `@stomp/stompjs`.
+ *
+ * {@link IMessage} is an extended IFrame.
+ */
+export interface IFrame {
+  /**
+   * STOMP Command
+   */
+  command: string;
+
+  /**
+   * Headers, key value pairs.
+   */
+  headers: StompHeaders;
+
+  /**
+   * Is this frame binary (based on whether body/binaryBody was passed when creating this frame).
+   */
+  isBinaryBody: boolean;
+
+  /**
+   * body of the frame as string
+   */
+  readonly body: string;
+
+  /**
+   * body as Uint8Array
+   */
+  readonly binaryBody: Uint8Array;
+}
+
+/**
+ * Alias for {@link IFrame}
+ */
+export type Frame = IFrame;