Add authenticator function used at reconnection (#650)

When the SDK reconnect to Kuzzle, it trigger the `reconnected` event. The Realtime controller will try to resubscribe when this event is triggered.

If the token had expired, then the Realtime controller will try to resubscribe with no authentication and thus the subscriptions request may fail.

This PR include a new `authenticator` property, this property should contain a function that authenticate the SDK (with `auth.login` for example).  
The SDK will call the function before emitting the reconnected event, if the SDK was authenticated and cannot re-authenticate then the `reconnected` event will not be emitted and the SDK will be in the `disconnected` state.

A new `reconnectionError` has been added and is triggered when the reconnection has failed

Author: Aschen

doc/7/core-classes/kuzzle/authenticate/index.md

@@ -0,0 +1,20 @@
+---
+code: true
+type: page
+title: authenticate
+description: Authenticate the SDK with the setted authenticator
+---
+
+# authenticate
+
+Authenticate the SDK by using the function set in the [authenticator](/sdk/js/7/core-classes/kuzzle/properties#authenticator) property.
+
+## Arguments
+
+```js
+authenticate();
+```
+
+## Usage
+
+<<< ./snippets/authenticate.js

doc/7/core-classes/kuzzle/authenticate/snippets/authenticate.js

@@ -0,0 +1,11 @@
+kuzzle.authenticator = async () => {
+  await kuzzle.auth.login('local', { username: 'foo', password: 'bar' });
+};
+
+try {
+  await kuzzle.authenticate();
+
+  console.log('Success');
+} catch (error) {
+  console.error(error.message);
+}

doc/7/core-classes/kuzzle/authenticate/snippets/authenticate.test.yml

@@ -0,0 +1,8 @@
+---
+name: kuzzle#authenticate
+description: Authenticate the SDK
+hooks:
+  before: curl -X POST kuzzle:7512/users/foo/_create -H "Content-Type:application/json" --data '{"content":{"profileIds":["default"]},"credentials":{"local":{"username":"foo","password":"bar"}}}'
+  after: curl -X DELETE kuzzle:7512/users/foo
+template: default
+expected: Success

doc/7/core-classes/kuzzle/properties/index.md

@@ -8,12 +8,12 @@ order: 10
 
 # Read-only properties
 
-| Property name        | Type     | Description          |
-| -------------------- | -------- | ---------------------|
-| `authenticated` | <pre>boolean</pre> | Returns `true` if the SDK holds a valid token |
-| `connected` | <pre>boolean</pre> | Returns `true` if the SDK is currently connected to a Kuzzle server. |
-| `offlineQueue` | <pre>object[]</pre> | Contains the queued requests during offline mode   |
-| `protocol` | <pre>Protocol</pre> | Protocol used by the SDK |
+| Property name   | Type                | Description                                                          |
+|-----------------|---------------------|----------------------------------------------------------------------|
+| `authenticated` | <pre>boolean</pre>  | Returns `true` if the SDK holds a valid token                        |
+| `connected`     | <pre>boolean</pre>  | Returns `true` if the SDK is currently connected to a Kuzzle server. |
+| `offlineQueue`  | <pre>object[]</pre> | Contains the queued requests during offline mode                     |
+| `protocol`      | <pre>Protocol</pre> | Protocol used by the SDK                                             |
 
 ### connected
 
@@ -24,18 +24,35 @@ See the associated documentation:
 
 # Writable properties
 
-| Property name        | Type     | Description          |
-| -------------------- | -------- | ---------------------|
-| `autoQueue` | <pre>boolean</pre> | If `true`, automatically queues all requests during offline mode |
-| `autoReplay` | <pre>boolean</pre> | If `true`, automatically replays queued requests on a `reconnected` event |
-| `autoResubscribe` | <pre>boolean</pre> | If `true`, automatically renews all subscriptions on a `reconnected` event |
-| `jwt` | <pre>string</pre> | Authentication token |
-| `offlineQueueLoader` | <pre>function</pre> | Called before dequeuing requests after exiting offline mode, to add items at the beginning of the offline queue  |
-| `queueFilter` | <pre>function</pre> | Custom function called during offline mode to filter queued requests on-the-fly |
-| `queueMaxSize` | <pre>number</pre>  | Number of maximum requests kept during offline mode|
-| `queueTTL` | <pre>number</pre>  | Time a queued request is kept during offline mode, in milliseconds |
-| `replayInterval` | <pre>number</pre>  | Delay between each replayed requests |
-| `volatile` | <pre>object</pre> | Common volatile data, will be sent to all future requests |
+| Property name        | Type                | Description                                                                                                     |
+|----------------------|---------------------|-----------------------------------------------------------------------------------------------------------------|
+| `authenticator`      | <pre>function</pre> | Authenticator function to authenticate the SDK. (After called, the `jwt` property of the SDK has to be set.)    |
+| `autoQueue`          | <pre>boolean</pre>  | If `true`, automatically queues all requests during offline mode                                                |
+| `autoReplay`         | <pre>boolean</pre>  | If `true`, automatically replays queued requests on a `reconnected` event                                       |
+| `autoResubscribe`    | <pre>boolean</pre>  | If `true`, automatically renews all subscriptions on a `reconnected` event                                      |
+| `jwt`                | <pre>string</pre>   | Authentication token                                                                                            |
+| `offlineQueueLoader` | <pre>function</pre> | Called before dequeuing requests after exiting offline mode, to add items at the beginning of the offline queue |
+| `queueFilter`        | <pre>function</pre> | Custom function called during offline mode to filter queued requests on-the-fly                                 |
+| `queueMaxSize`       | <pre>number</pre>   | Number of maximum requests kept during offline mode                                                             |
+| `queueTTL`           | <pre>number</pre>   | Time a queued request is kept during offline mode, in milliseconds                                              |
+| `replayInterval`     | <pre>number</pre>   | Delay between each replayed requests                                                                            |
+| `volatile`           | <pre>object</pre>   | Common volatile data, will be sent to all future requests                                                       |
+
+### authenticator
+
+The `authenticator` property can be set to a function returning a promise.
+
+This function will be called after a successful reconnection if the current authentication token is not valid anymore.  
+
+This function has to authenticate the SDK. It can be a call to [auth.login](/sdk/js/7/controllers/auth/login) for example.
+
+```js
+kuzzle.authenticator = async () => {
+  await kuzzle.auth.login('local', { username: 'user', password: 'pass' });
+}
+```
+
+If the `authenticator` function fail to authenticate the SDK, then the `reconnected` event is never emitted and a `reconnectionError` event is emitted.
 
 ### offlineQueueLoader
 
@@ -49,11 +66,11 @@ Promise<Object[]> offlineQueueLoader()
 
 The returned (or resolved) array must contain objects, each with the following properties:
 
-| Property | Type | Description |
-|---|---|---|
-| `query` | <pre>object</pre> | Object representing the request that is about to be sent to Kuzzle, following the [Kuzzle API](/core/2/guides/main-concepts/querying) format |
-| `reject` | <pre>function</pre> | A [Promise.reject](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise/reject) function |
-| `resolve` | <pre>function</pre> | A [Promise.resolve](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise/resolve) function |
+| Property  | Type                | Description                                                                                                                                  |
+|-----------|---------------------|----------------------------------------------------------------------------------------------------------------------------------------------|
+| `query`   | <pre>object</pre>   | Object representing the request that is about to be sent to Kuzzle, following the [Kuzzle API](/core/2/guides/main-concepts/querying) format |
+| `reject`  | <pre>function</pre> | A [Promise.reject](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise/reject) function                 |
+| `resolve` | <pre>function</pre> | A [Promise.resolve](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise/resolve) function               |
 
 ### queueFilter
 

doc/7/essentials/offline-tools/index.md

@@ -11,6 +11,33 @@ order: 400
 The Kuzzle SDK provides a set of properties that helps your application to be resilient to the loss of network connection
 during its lifespan.
 
+## Authentication after reconnection
+
+When the SDK reconnect, the authentication token may not be valid anymore.
+
+It's possible to set the [authenticator](/sdk/js/7/core-classes/kuzzle/properties#authenticator) function to allows the SDK to re-authenticate after a successful reconnection.
+
+<details><summary>Example to automatically re-authenticate on reconnection</summary>
+
+```js
+const { Kuzzle, WebSocket } = require('kuzzle');
+
+const kuzzle = new Kuzzle(new WebSocket('localhost'), { autoResubscribe: true });
+
+kuzzle.authenticator = async () => {
+  await kuzzle.auth.login('local', { username: 'test', password: 'test' });
+};
+
+await kuzzle.connect();
+await kuzzle.authenticate();
+
+await kuzzle.realtime.subscribe('test', 'test', {}, () => {
+  console.log('Received');
+});
+```
+
+</details>
+
 ## Contructor options and properties
 
 These properties can be set in the `options` object when [instantiating a new SDK](/sdk/js/7/core-classes/kuzzle/constructor#arguments).
@@ -77,6 +104,10 @@ A read-only `number` specifying the time in milliseconds between different recon
 
 Default value: *Depends on the Protocol*
 
+### reconnectionError
+
+Emitted when the SDK reconnect to Kuzzle and does not have a valid authentication token or can't renew it with the [authenticator](/sdk/js/7/core-classes/kuzzle/properties#authenticator) function.
+
 ## Methods
 
 ### [flushQueue()](/sdk/js/7/core-classes/kuzzle/flush-queue)

src/Kuzzle.ts

@@ -32,6 +32,7 @@ const events = [
   'offlineQueuePop',
   'queryError',
   'reconnected',
+  'reconnectionError',
   'tokenExpired'
 ];
 
@@ -42,41 +43,46 @@ export class Kuzzle extends KuzzleEventEmitter {
   /**
    * Protocol used by the SDK to communicate with Kuzzle.
    */
-  public protocol: any;
+  protocol: any;
   /**
    * If true, automatically renews all subscriptions on a reconnected event.
    */
-  public autoResubscribe: boolean;
+  autoResubscribe: boolean;
   /**
    * Timeout before sending again a similar event.
    */
-  public eventTimeout: number;
+  eventTimeout: number;
   /**
    * SDK version.
    */
-  public sdkVersion: string;
+  sdkVersion: string;
   /**
    * SDK name (e.g: `[email protected]`).
    */
-  public sdkName: string;
+  sdkName: string;
   /**
    * Common volatile data that will be sent to all future requests.
    */
-  public volatile: JSONObject;
+  volatile: JSONObject;
   /**
    * Handle deprecation warning in development mode (hidden in production)
    */
-  public deprecationHandler: Deprecation;
-
-  public auth: AuthController;
-  public bulk: any;
-  public collection: CollectionController;
-  public document: DocumentController;
-  public index: IndexController;
-  public ms: any;
-  public realtime: RealtimeController;
-  public security: any;
-  public server: any;
+  deprecationHandler: Deprecation;
+  /**
+   * Authenticator function called after a reconnection if the SDK is no longer
+   * authenticated.
+   */
+  authenticator: () => Promise<void> = null;
+
+  auth: AuthController;
+  bulk: any;
+  collection: CollectionController;
+  document: DocumentController;
+  index: IndexController;
+  ms: any;
+  realtime: RealtimeController;
+  security: any;
+  server: any;
 
   private _protectedEvents: any;
   private _offlineQueue: any;
@@ -236,38 +242,38 @@ export class Kuzzle extends KuzzleEventEmitter {
     this._cookieAuthentication = typeof options.cookieAuth === 'boolean'
       ? options.cookieAuth
       : false;
-    
+
     if (this._cookieAuthentication) {
       this.protocol.enableCookieSupport();
       let autoQueueState;
       let autoReplayState;
       let autoResbuscribeState;
-  
+
       this.protocol.addListener('websocketRenewalStart', () => {
         autoQueueState = this.autoQueue;
         autoReplayState = this.autoReplay;
         autoResbuscribeState = this.autoResubscribe;
-  
+
         this.autoQueue = true;
         this.autoReplay = true;
         this.autoResubscribe = true;
       });
-  
+
       this.protocol.addListener('websocketRenewalDone', () => {
         this.autoQueue = autoQueueState;
         this.autoReplay = autoReplayState;
         this.autoResubscribe = autoResbuscribeState;
       });
     }
-    
+
     this.deprecationHandler = new Deprecation(
       typeof options.deprecationWarning === 'boolean' ? options.deprecationWarning : true
     );
-    
+
     if (this._cookieAuthentication && typeof XMLHttpRequest === 'undefined') {
       throw new Error('Support for cookie authentication with cookieAuth option is not supported outside a browser');
     }
-    
+
     // controllers
     this.useController(AuthController, 'auth');
     this.useController(BulkController, 'bulk');
@@ -525,11 +531,19 @@ export class Kuzzle extends KuzzleEventEmitter {
       this.emit('disconnected', context);
     });
 
-    this.protocol.addListener('reconnect', () => {
+    this.protocol.addListener('reconnect', async () => {
       if (this.autoQueue) {
         this.stopQueuing();
       }
 
+      // If an authenticator was set, check if the token is still valid and try
+      // to re-authenticate if needed. Otherwise the SDK is in disconnected state.
+      if (this.authenticator && ! await this.tryReAuthenticate()) {
+        this.disconnect();
+
+        return;
+      }
+
       if (this.autoReplay) {
         this.playQueue();
       }
@@ -542,6 +556,56 @@ export class Kuzzle extends KuzzleEventEmitter {
     return this.protocol.connect();
   }
 
+  /**
+   * Try to re-authenticate the SDK if the current token is invalid.
+   *
+   * If the token is invalid, this method will return false and emit a
+   * "reconnectionError" event when:
+   *   - the SDK cannot re-authenticate using the authenticator function
+   *   - the authenticator function is not set
+   *
+   * This method never returns a rejected promise.
+   */
+  private async tryReAuthenticate (): Promise<boolean> {
+    try {
+      const { valid } = await this.auth.checkToken();
+
+      if (valid) {
+        return true;
+      }
+
+      await this.authenticate();
+
+      return true;
+    }
+    catch (err) {
+      this.emit('reconnectionError', {
+        error: new Error(`Failed to authenticate the SDK after reconnection: ${err}`)
+      });
+
+      return false;
+    }
+  }
+
+  /**
+   * Use the "authenticator" function to authenticate the SDK.
+   *
+   * @returns The authentication token
+   */
+  async authenticate (): Promise<void> {
+    if (typeof this.authenticator !== 'function') {
+      throw new Error('The "authenticator" property must be a function.');
+    }
+
+    await this.authenticator();
+
+    const { valid } = await this.auth.checkToken();
+
+    if (! valid) {
+      throw new Error('The "authenticator" function failed to authenticate the SDK.');
+    }
+  }
+
   /**
    * Adds a listener to a Kuzzle global event. When an event is fired, listeners are called in the order of their
    * insertion.
@@ -801,7 +865,7 @@ Discarded request: ${JSON.stringify(request)}`));
       uniqueQueue = {},
       dequeuingProcess = () => {
         if (this.offlineQueue.length > 0) {
-          
+
           this._timeoutRequest(
             this.offlineQueue[0].timeout,
             this.offlineQueue[0].request,
@@ -853,7 +917,7 @@ Discarded request: ${JSON.stringify(request)}`));
 
   /**
    * Sends a request with a timeout
-   * 
+   *
    * @param delay Delay before the request is rejected if not resolved
    * @param request Request object
    * @param options Request options