Merge pull request #639 from kuzzleio/638-disconnection-origin

Add an origin parameter to the kuzzle disconnected event

Author: Shiranuit

doc/7/essentials/events/index.md

@@ -32,6 +32,22 @@ Triggered when Kuzzle discards a request, typically if no connection is establis
 
 Triggered when the current session has been unexpectedly disconnected.
 
+<SinceBadge version="auto-version"/>
+**Callback arguments:**
+
+`@param {object} context`
+
+| Property | Type              | Description                                |
+| -------- | ----------------- | ------------------------------------------ |
+| `origin` | <pre>string</pre> | Indicate what is causing the disconnection |
+
+**Origins**
+
+| Name                     | Description                                                                                                                                                        |
+| ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `websocket/auth-renewal` | The websocket protocol si reconnecting to renew the token. See [Websocket Cookie Authentication](sdk/js/7/protocols/websocket/introduction#cookie-authentication). |
+| `user/connection-closed` | The disconnection is done by the user.                                                                                                                             |
+| `network/error`          | An network error occured and caused a disconnection.                                                                                                               |
 ## loginAttempt
 
 Triggered when a login attempt completes, either with a success or a failure result.
@@ -75,8 +91,8 @@ Triggered whenever a request is added to the offline queue.
 
 `@param {object} data`
 
-| Property  | Type              | Description                                                        |
-| --------- | ----------------- | ------------------------------------------------------------------ |
+| Property  | Type              | Description                                                         |
+| --------- | ----------------- | ------------------------------------------------------------------- |
 | `request` | <pre>object</pre> | [Request](/core/2/guides/main-concepts/querying) added to the queue |
 
 ## queryError

src/Kuzzle.ts

@@ -521,8 +521,8 @@ export class Kuzzle extends KuzzleEventEmitter {
       this.emit('networkError', error);
     });
 
-    this.protocol.addListener('disconnect', () => {
-      this.emit('disconnected');
+    this.protocol.addListener('disconnect', context => {
+      this.emit('disconnected', context);
     });
 
     this.protocol.addListener('reconnect', () => {

src/protocols/DisconnectionOrigin.ts

@@ -0,0 +1,9 @@
+const WEBSOCKET_AUTH_RENEWAL = 'websocket/auth-renewal';
+const USER_CONNECTION_CLOSED = 'user/connection-closed';
+const NETWORK_ERROR = 'network/error';
+
+export {
+  WEBSOCKET_AUTH_RENEWAL,
+  USER_CONNECTION_CLOSED,
+  NETWORK_ERROR,
+};

src/protocols/WebSocket.ts

@@ -5,6 +5,7 @@ import { BaseProtocolRealtime } from './abstract/Realtime';
 import { JSONObject } from '../types';
 import { RequestPayload } from '../types/RequestPayload';
 import HttpProtocol from './Http';
+import * as DisconnectionOrigin from './DisconnectionOrigin';
 
 /**
  * WebSocket protocol used to connect to a Kuzzle server.
@@ -145,7 +146,7 @@ export default class WebSocketProtocol extends BaseProtocolRealtime {
         }
 
         if (status === 1000) {
-          this.clientDisconnected();
+          this.clientDisconnected(DisconnectionOrigin.USER_CONNECTION_CLOSED);
         }
         // do not forward a connection close error if no
         // connection has been previously established
@@ -266,7 +267,7 @@ export default class WebSocketProtocol extends BaseProtocolRealtime {
       this.client.close();
     }
     this.client = null;
-    this.clientDisconnected(); // Simulate a disconnection, this will enable offline queue and trigger realtime subscriptions backup
+    this.clientDisconnected(DisconnectionOrigin.WEBSOCKET_AUTH_RENEWAL); // Simulate a disconnection, this will enable offline queue and trigger realtime subscriptions backup
 
     this._httpProtocol._sendHttpRequest(formattedRequest)
       .then(response => {
@@ -284,10 +285,10 @@ export default class WebSocketProtocol extends BaseProtocolRealtime {
   /**
    * @override
    */
-  clientDisconnected() {
+  clientDisconnected(origin: string) {
     clearInterval(this.pingIntervalId);
     clearTimeout(this.pongTimeoutId);
-    super.clientDisconnected();
+    super.clientDisconnected(origin);
   }
 
   /**

src/protocols/abstract/Realtime.ts

@@ -1,6 +1,7 @@
 'use strict';
 
 import { KuzzleAbstractProtocol } from './Base';
+import * as DisconnectionOrigin from '../DisconnectionOrigin';
 
 export abstract class BaseProtocolRealtime extends KuzzleAbstractProtocol {
   protected _autoReconnect: boolean;
@@ -51,10 +52,12 @@ export abstract class BaseProtocolRealtime extends KuzzleAbstractProtocol {
 
   /**
    * Called when the client's connection is closed
+   * 
+   * @param {string} origin String that describe what is causing the disconnection
    */
-  clientDisconnected () {
+  clientDisconnected (origin: string) {
     this.clear();
-    this.emit('disconnect');
+    this.emit('disconnect', { origin });
   }
 
   /**
@@ -93,7 +96,7 @@ export abstract class BaseProtocolRealtime extends KuzzleAbstractProtocol {
       }, this.reconnectionDelay);
     }
     else {
-      this.emit('disconnect');
+      this.emit('disconnect', { origin: DisconnectionOrigin.NETWORK_ERROR });
     }
   }
 

test/mocks/protocol.mock.js

@@ -1,6 +1,7 @@
 const
   sinon = require('sinon'),
-  { KuzzleEventEmitter } = require('../../src/core/KuzzleEventEmitter');
+  { KuzzleEventEmitter } = require('../../src/core/KuzzleEventEmitter'),
+  DisconnectionOrigin = require('../../src/protocols/DisconnectionOrigin');
 
 class ProtocolMock extends KuzzleEventEmitter {
 
@@ -54,7 +55,7 @@ class ProtocolMock extends KuzzleEventEmitter {
 
   disconnect () {
     this.state = 'offline';
-    this.emit('disconnect');
+    this.emit('disconnect', {origin: DisconnectionOrigin.USER_CONNECTION_CLOSED });
   }
 
   send (request) {

test/protocol/WebSocket.test.js

@@ -6,6 +6,7 @@ const NodeWS = require('ws');
 const { default: WS } = require('../../src/protocols/WebSocket');
 const windowMock = require('../mocks/window.mock');
 const { default: HttpProtocol } = require('../../src/protocols/Http');
+const DisconnectionOrigin = require('../../src/protocols/DisconnectionOrigin');
 
 describe('WebSocket networking module', () => {
   let
@@ -160,6 +161,7 @@ describe('WebSocket networking module', () => {
     websocket.connect = sinon.stub().resolves();
     clientStub.onopen();
     clientStub.onclose(1000);
+    should(cb).be.calledOnce().and.be.calledWith({origin: DisconnectionOrigin.USER_CONNECTION_CLOSED });
     websocket.close();
     should(clearTimeout)
       .be.calledOnce();
@@ -188,6 +190,7 @@ describe('WebSocket networking module', () => {
 
   it('should not try to reconnect on a connection error with autoReconnect = false', () => {
     const cb = sinon.stub();
+    const disconnectCB = sinon.stub();
 
     websocket = new WS('address', {
       port: 1234,
@@ -196,6 +199,7 @@ describe('WebSocket networking module', () => {
     });
 
     websocket.retrying = false;
+    websocket.addListener('disconnect', disconnectCB);
     websocket.addListener('networkError', cb);
     should(websocket.listeners('networkError').length).be.eql(1);
 
@@ -205,6 +209,7 @@ describe('WebSocket networking module', () => {
     clock.tick(10);
 
     should(cb).be.calledOnce();
+    should(disconnectCB).be.calledOnce().and.be.calledWith({ origin: DisconnectionOrigin.NETWORK_ERROR });
     should(websocket.retrying).be.false();
     should(websocket.connect).not.be.called();
 
@@ -276,7 +281,7 @@ describe('WebSocket networking module', () => {
     clientStub.onclose(1000);
 
     clock.tick(10);
-    should(cb).be.calledOnce();
+    should(cb).be.calledOnce().and.be.calledWith({ origin: DisconnectionOrigin.USER_CONNECTION_CLOSED });
     should(websocket.listeners('disconnect').length).be.eql(1);
     websocket.clear.should.be.calledOnce();
   });
@@ -724,7 +729,7 @@ describe('WebSocket networking module', () => {
         });
 
         await should(clientStub.close).be.calledOnce();
-        await should(websocket.clientDisconnected).be.calledOnce();
+        await should(websocket.clientDisconnected).be.calledOnce().and.calledWith(DisconnectionOrigin.WEBSOCKET_AUTH_RENEWAL);
         await should(clientStub.send).not.be.called();
 
         await should(onRenewalStart).be.calledOnce();