@stomp/stompjs 7.0.1 → 7.1.1

package/src/client.ts

@@ -11,7 +11,9 @@ import {
   IPublishParams,
   IStompSocket,
   messageCallbackType,
+  ReconnectionTimeMode,
   StompSocketState,
+  TickerStrategy,
   wsErrorCallbackType,
 } from './types.js';
 import { Versions } from './versions.js';
@@ -90,6 +92,33 @@ export class Client {
    */
   public reconnectDelay: number = 5000;
 
+  /**
+   * tracking the time to the next reconnection. Initialized to [Client#reconnectDelay]{@link Client#reconnectDelay}'s value and it may
+   * change depending on the [Client#reconnectTimeMode]{@link Client#reconnectTimeMode} setting
+   */
+  private _nextReconnectDelay: number = 0;
+
+  /**
+   * Maximum time to wait between reconnects, in milliseconds. Defaults to 15 minutes.
+   * Only relevant when [Client#reconnectTimeMode]{@link Client#reconnectTimeMode} not LINEAR (e.g., EXPONENTIAL).
+   * Set to 0 for no limit on wait time.
+   */
+  public maxReconnectDelay: number = 15 * 60 * 1000; // 15 minutes in ms
+
+  /**
+   * Reconnection wait time mode, either linear (default) or exponential.
+   * Note: See [Client#maxReconnectDelay]{@link Client#maxReconnectDelay} for setting the maximum delay when exponential
+   *
+   * ```javascript
+   * client.configure({
+   *   reconnectTimeMode: ReconnectionTimeMode.EXPONENTIAL,
+   *   reconnectDelay: 200, // It will wait 200, 400, 800 ms...
+   *   maxReconnectDelay: 10000, // Optional, when provided, it will not wait more that these ms
+   * })
+   * ```
+   */
+  public reconnectTimeMode: ReconnectionTimeMode = ReconnectionTimeMode.LINEAR;
+
   /**
    * Incoming heartbeat interval in milliseconds. Set to 0 to disable.
    */
@@ -100,6 +129,23 @@ export class Client {
    */
   public heartbeatOutgoing: number = 10000;
 
+  /**
+   * Outgoing heartbeat strategy.
+   * See https://github.com/stomp-js/stompjs/pull/579
+   *
+   * Can be worker or interval strategy, but will always use `interval`
+   * if web workers are unavailable, for example, in a non-browser environment.
+   *
+   * Using Web Workers may work better on long-running pages
+   * and mobile apps, as the browser may suspend Timers in the main page.
+   * Try the `Worker` mode if you discover disconnects when the browser tab is in the background.
+   *
+   * When used in a JS environment, use 'worker' or 'interval' as valid values.
+   *
+   * Defaults to `interval` strategy.
+   */
+  public heartbeatStrategy: TickerStrategy = TickerStrategy.Interval;
+
   /**
    * This switches on a non-standard behavior while sending WebSocket packets.
    * It splits larger (text) packets into chunks of [maxWebSocketChunkSize]{@link Client#maxWebSocketChunkSize}.
@@ -221,7 +267,7 @@ export class Client {
    * This can be used to reliably fetch credentials, access token etc. from some other service
    * in an asynchronous way.
    */
-  public beforeConnect: () => void | Promise<void>;
+  public beforeConnect: (client: Client) => void | Promise<void>;
 
   /**
    * Callback, invoked on every successful connection to the STOMP broker.
@@ -375,12 +421,24 @@ export class Client {
   public configure(conf: StompConfig): void {
     // bulk assign all properties to this
     (Object as any).assign(this, conf);
+
+    // Warn on incorrect maxReconnectDelay settings
+    if (
+      this.maxReconnectDelay > 0 &&
+      this.maxReconnectDelay < this.reconnectDelay
+    ) {
+      this.debug(
+        `Warning: maxReconnectDelay (${this.maxReconnectDelay}ms) is less than reconnectDelay (${this.reconnectDelay}ms). Using reconnectDelay as the maxReconnectDelay delay.`,
+      );
+      this.maxReconnectDelay = this.reconnectDelay;
+    }
   }
 
   /**
    * Initiate the connection with the broker.
    * If the connection breaks, as per [Client#reconnectDelay]{@link Client#reconnectDelay},
-   * it will keep trying to reconnect.
+   * it will keep trying to reconnect. If the [Client#reconnectTimeMode]{@link Client#reconnectTimeMode}
+   * is set to EXPONENTIAL it will increase the wait time exponentially
    *
    * Call [Client#deactivate]{@link Client#deactivate} to disconnect and stop reconnection attempts.
    */
@@ -393,6 +451,7 @@ export class Client {
 
       this._changeState(ActivationState.ACTIVE);
 
+      this._nextReconnectDelay = this.reconnectDelay;
       this._connect();
     };
 
@@ -408,16 +467,18 @@ export class Client {
   }
 
   private async _connect(): Promise<void> {
-    await this.beforeConnect();
+    await this.beforeConnect(this);
 
     if (this._stompHandler) {
-      this.debug('There is already a stompHandler, skipping the call to connect');
+      this.debug(
+        'There is already a stompHandler, skipping the call to connect',
+      );
       return;
     }
 
     if (!this.active) {
       this.debug(
-        'Client has been marked inactive, will not attempt to connect'
+        'Client has been marked inactive, will not attempt to connect',
       );
       return;
     }
@@ -435,7 +496,7 @@ export class Client {
         // Connection not established, close the underlying socket
         // a reconnection will be attempted
         this.debug(
-          `Connection not established in ${this.connectionTimeout}ms, closing socket`
+          `Connection not established in ${this.connectionTimeout}ms, closing socket`,
         );
         this.forceDisconnect();
       }, this.connectionTimeout);
@@ -453,6 +514,7 @@ export class Client {
       disconnectHeaders: this._disconnectHeaders,
       heartbeatIncoming: this.heartbeatIncoming,
       heartbeatOutgoing: this.heartbeatOutgoing,
+      heartbeatStrategy: this.heartbeatStrategy,
       splitLargeFrames: this.splitLargeFrames,
       maxWebSocketChunkSize: this.maxWebSocketChunkSize,
       forceBinaryWSFrames: this.forceBinaryWSFrames,
@@ -469,7 +531,7 @@ export class Client {
 
         if (!this.active) {
           this.debug(
-            'STOMP got connected while deactivate was issued, will disconnect now'
+            'STOMP got connected while deactivate was issued, will disconnect now',
           );
           this._disposeStompHandler();
           return;
@@ -523,7 +585,7 @@ export class Client {
     } else if (this.brokerURL) {
       webSocket = new WebSocket(
         this.brokerURL,
-        this.stompVersions.protocolVersions()
+        this.stompVersions.protocolVersions(),
       );
     } else {
       throw new Error('Either brokerURL or webSocketFactory must be provided');
@@ -533,12 +595,26 @@ export class Client {
   }
 
   private _schedule_reconnect(): void {
-    if (this.reconnectDelay > 0) {
-      this.debug(`STOMP: scheduling reconnection in ${this.reconnectDelay}ms`);
+    if (this._nextReconnectDelay > 0) {
+      this.debug(
+        `STOMP: scheduling reconnection in ${this._nextReconnectDelay}ms`,
+      );
 
       this._reconnector = setTimeout(() => {
+        if (this.reconnectTimeMode === ReconnectionTimeMode.EXPONENTIAL) {
+          this._nextReconnectDelay = this._nextReconnectDelay * 2;
+
+          // Truncated exponential backoff with a set limit unless disabled
+          if (this.maxReconnectDelay !== 0) {
+            this._nextReconnectDelay = Math.min(
+              this._nextReconnectDelay,
+              this.maxReconnectDelay,
+            );
+          }
+        }
+
         this._connect();
-      }, this.reconnectDelay);
+      }, this._nextReconnectDelay);
     }
   }
 
@@ -577,6 +653,9 @@ export class Client {
 
     this._changeState(ActivationState.DEACTIVATING);
 
+    // Reset reconnection timer just to be safe
+    this._nextReconnectDelay = 0;
+
     // Clear if a reconnection was scheduled
     if (this._reconnector) {
       clearTimeout(this._reconnector);
@@ -747,7 +826,7 @@ export class Client {
   public subscribe(
     destination: string,
     callback: messageCallbackType,
-    headers: StompHeaders = {}
+    headers: StompHeaders = {},
   ): StompSubscription {
     this._checkConnection();
     // @ts-ignore - we already checked that there is a _stompHandler, and it is connected
@@ -835,7 +914,7 @@ export class Client {
   public ack(
     messageId: string,
     subscriptionId: string,
-    headers: StompHeaders = {}
+    headers: StompHeaders = {},
   ): void {
     this._checkConnection();
     // @ts-ignore - we already checked that there is a _stompHandler, and it is connected
@@ -858,7 +937,7 @@ export class Client {
   public nack(
     messageId: string,
     subscriptionId: string,
-    headers: StompHeaders = {}
+    headers: StompHeaders = {},
   ): void {
     this._checkConnection();
     // @ts-ignore - we already checked that there is a _stompHandler, and it is connected

package/src/i-transaction.ts

@@ -2,8 +2,6 @@
  * A Transaction is created by calling [Client#begin]{@link Client#begin}
  *
  * Part of `@stomp/stompjs`.
- *
- * TODO: Example and caveat
  */
 export interface ITransaction {
   /**

package/src/stomp-config.ts

@@ -1,13 +1,16 @@
 import { StompHeaders } from './stomp-headers.js';
 import {
   ActivationState,
+  TickerStrategy,
   closeEventCallbackType,
   debugFnType,
   frameCallbackType,
   messageCallbackType,
+  ReconnectionTimeMode,
   wsErrorCallbackType,
 } from './types.js';
 import { Versions } from './versions.js';
+import { Client } from './client.js';
 
 /**
  * Configuration options for STOMP Client, each key corresponds to
@@ -42,6 +45,16 @@ export class StompConfig {
    */
   public reconnectDelay?: number;
 
+  /**
+   * See [Client#maxReconnectDelay]{@link Client#maxReconnectDelay}
+   */
+  public maxReconnectDelay?: number;
+
+  /**
+   * See [Client#reconnectTimeMode]{@link Client#reconnectTimeMode}
+   */
+  public reconnectTimeMode?: ReconnectionTimeMode;
+
   /**
    * See [Client#heartbeatIncoming]{@link Client#heartbeatIncoming}.
    */
@@ -52,6 +65,11 @@ export class StompConfig {
    */
   public heartbeatOutgoing?: number;
 
+  /**
+   * See [Client#heartbeatStrategy]{@link Client#heartbeatStrategy}.
+   */
+  public heartbeatStrategy?: TickerStrategy;
+
   /**
    * See [Client#splitLargeFrames]{@link Client#splitLargeFrames}.
    */
@@ -100,7 +118,7 @@ export class StompConfig {
   /**
    * See [Client#beforeConnect]{@link Client#beforeConnect}.
    */
-  public beforeConnect?: () => void | Promise<void>;
+  public beforeConnect?: (client: Client) => void | Promise<void>;
 
   /**
    * See [Client#onConnect]{@link Client#onConnect}.

package/src/stomp-handler.ts

@@ -1,3 +1,4 @@
+import { augmentWebsocket } from './augment-websocket.js';
 import { BYTE } from './byte.js';
 import { Client } from './client.js';
 import { FrameImpl } from './frame-impl.js';
@@ -6,6 +7,7 @@ import { ITransaction } from './i-transaction.js';
 import { Parser } from './parser.js';
 import { StompHeaders } from './stomp-headers.js';
 import { StompSubscription } from './stomp-subscription.js';
+import { Ticker } from './ticker.js';
 import {
   closeEventCallbackType,
   debugFnType,
@@ -19,7 +21,6 @@ import {
   wsErrorCallbackType,
 } from './types.js';
 import { Versions } from './versions.js';
-import { augmentWebsocket } from './augment-websocket.js';
 
 /**
  * The STOMP protocol handler
@@ -85,7 +86,7 @@ export class StompHandler {
   private _partialData: string;
   private _escapeHeaderValues: boolean;
   private _counter: number;
-  private _pinger: any;
+  private _pinger?: Ticker;
   private _ponger: any;
   private _lastServerActivityTS: number;
 
@@ -289,12 +290,14 @@ export class StompHandler {
     if (this.heartbeatOutgoing !== 0 && serverIncoming !== 0) {
       const ttl: number = Math.max(this.heartbeatOutgoing, serverIncoming);
       this.debug(`send PING every ${ttl}ms`);
-      this._pinger = setInterval(() => {
+
+      this._pinger = new Ticker(ttl, this._client.heartbeatStrategy, this.debug);
+      this._pinger.start(() => {
         if (this._webSocket.readyState === StompSocketState.OPEN) {
           this._webSocket.send(BYTE.LF);
           this.debug('>>> PING');
         }
-      }, ttl);
+      });
     }
 
     if (this.heartbeatIncoming !== 0 && serverOutgoing !== 0) {
@@ -426,7 +429,7 @@ export class StompHandler {
     this._connected = false;
 
     if (this._pinger) {
-      clearInterval(this._pinger);
+      this._pinger.stop();
       this._pinger = undefined;
     }
     if (this._ponger) {

package/src/ticker.ts

@@ -0,0 +1,76 @@
+import { debugFnType, TickerStrategy } from './types.js';
+
+export class Ticker {
+  private readonly _workerScript = `
+    var startTime = Date.now();
+    setInterval(function() {
+        self.postMessage(Date.now() - startTime);
+    }, ${this._interval});
+  `;
+
+  private _worker?: Worker;
+  private _timer?: any;
+
+  constructor(
+    private readonly _interval: number,
+    private readonly _strategy = TickerStrategy.Interval,
+    private readonly _debug: debugFnType) {
+  }
+
+  public start(tick: (elapsedTime: number) => void): void {
+    this.stop();
+
+    if (this.shouldUseWorker()) {
+      this.runWorker(tick);
+    } else {
+      this.runInterval(tick);
+    }
+  }
+
+  public stop(): void {
+    this.disposeWorker();
+    this.disposeInterval();
+  }
+
+  private shouldUseWorker(): boolean {
+    return typeof(Worker) !== 'undefined' && this._strategy === TickerStrategy.Worker
+  }
+
+  private runWorker(tick: (elapsedTime: number) => void): void {
+    this._debug('Using runWorker for outgoing pings');
+    if (!this._worker) {
+      this._worker = new Worker(
+        URL.createObjectURL(
+          new Blob([this._workerScript], { type: 'text/javascript' })
+        )
+      );
+      this._worker.onmessage = (message) => tick(message.data);
+    }
+  }
+
+  private runInterval(tick: (elapsedTime: number) => void): void {
+    this._debug('Using runInterval for outgoing pings');
+    if (!this._timer) {
+      const startTime = Date.now();
+      this._timer = setInterval(() => {
+        tick(Date.now() - startTime);
+      }, this._interval);
+    }
+  }
+
+  private disposeWorker(): void {
+    if (this._worker) {
+      this._worker.terminate();
+      delete this._worker;
+      this._debug('Outgoing ping disposeWorker');
+    }
+  }
+
+  private disposeInterval(): void {
+    if (this._timer) {
+      clearInterval(this._timer);
+      delete this._timer;
+      this._debug('Outgoing ping disposeInterval');
+    }
+  }
+}

package/src/types.ts

@@ -157,6 +157,22 @@ export enum ActivationState {
   INACTIVE,
 }
 
+/**
+ * Possible reconnection wait time modes
+ */
+export enum ReconnectionTimeMode {
+  LINEAR,
+  EXPONENTIAL
+}
+
+/**
+ * Possible ticker strategies for outgoing heartbeat ping
+ */
+export enum TickerStrategy {
+  Interval = 'interval',
+  Worker = 'worker'
+}
+
 /**
  * @internal
  */
@@ -167,6 +183,7 @@ export interface IStomptHandlerConfig {
   disconnectHeaders: StompHeaders;
   heartbeatIncoming: number;
   heartbeatOutgoing: number;
+  heartbeatStrategy: TickerStrategy;
   splitLargeFrames: boolean;
   maxWebSocketChunkSize: number;
   forceBinaryWSFrames: boolean;