Add debug mode (#680)

Adds a debug mode for the SDK that prints every requests and responses.

To activate in Node.js: export DEBUG=kuzzle-sdk

To activate in the Browser: add the following search param in the URL ?debugKuzzleSdk

Author: Aschen

doc/7/essentials/debugging/index.md

@@ -0,0 +1,43 @@
+---
+code: false
+type: page
+title: Debugging
+description: How to debug the SDK in your application
+order: 600
+---
+
+# Debugging
+
+The SDK internal behavior can be observed for debugging purposes.
+
+## Events listening
+
+The SDK emits internal events, the complete list is available here: [Events](/sdk/js/7/essentials/events).
+
+You can listen to every event and print payload contents with the following snippet:
+
+```js
+for (const event of kuzzle.events) {
+  kuzzle.on(event, (...args) =>  console.log(event, ...args));
+}
+```
+
+## Print Request and Response
+
+<SinceBadge version="auto-version"/>
+
+You can print every request sent to Kuzzle and every response sent back to the SDK by activating the debug mode.
+
+In Node.js, the `DEBUG` environment variable should contain the `kuzzle-sdk` string.
+
+```bash
+export DEBUG=kuzzle-sdk
+
+# Run your program
+```
+
+In the Browser, you need to add the `debugKuzzleSdk` search param in the URL.
+
+```
+http://my-application.by/devices?debugKuzzleSdk
+```

src/Kuzzle.ts

@@ -14,6 +14,7 @@ import { MemoryStorageController } from './controllers/MemoryStorage';
 import { Deprecation } from './utils/Deprecation';
 import { uuidv4 } from './utils/uuidv4';
 import { proxify } from './utils/proxify';
+import { debug } from './utils/debug';
 import { JSONObject } from './types';
 import { RequestPayload } from './types/RequestPayload';
 import { ResponsePayload } from './types/ResponsePayload';
@@ -823,7 +824,9 @@ export class Kuzzle extends KuzzleEventEmitter {
     if (this._queuing) {
       if (queuable) {
         this._cleanQueue();
-        this.emit('offlineQueuePush', {request});
+
+        this.emit('offlineQueuePush', { request });
+
         return new Promise((resolve, reject) => {
           this.offlineQueue.push({
             resolve,
@@ -844,7 +847,11 @@ Discarded request: ${JSON.stringify(request)}`));
       requestTimeout,
       request,
       options
-    ).then((response: ResponsePayload) => this.deprecationHandler.logDeprecation(response));
+    ).then((response: ResponsePayload) => {
+      debug('RESPONSE', response);
+
+      return this.deprecationHandler.logDeprecation(response);
+    });
   }
 
   /**
@@ -1044,6 +1051,8 @@ Discarded request: ${JSON.stringify(request)}`));
    * @returns Resolved request or a TimedOutError
    */
   private _timeoutRequest(delay: number, request: RequestPayload, options: JSONObject = {}) {
+    debug('REQUEST', request);
+
     // No timeout
     if (delay === -1) {
       return this.protocol.query(request, options);

src/controllers/Auth.ts

@@ -49,7 +49,7 @@ export class AuthController extends BaseController {
    * Do not add the token for the checkToken route, to avoid getting a token error when
    * a developer simply wishes to verify their token
    */
-  authenticateRequest (request: any) {
+  authenticateRequest (request: RequestPayload) {
     if (this.kuzzle.cookieAuthentication) {
       return;
     }
@@ -216,7 +216,7 @@ export class AuthController extends BaseController {
         token = this.authenticationToken.encodedJwt;
       }
     }
-    
+
     return this.query({
       action: 'checkToken',
       body: { token },

src/utils/Deprecation.ts

@@ -1,29 +1,28 @@
 import { ResponsePayload } from '../types/ResponsePayload';
 
 export class Deprecation {
-
-  private _deprecationWarning: boolean;
+  private deprecationWarning: boolean;
 
   constructor (deprecationWarning: boolean) {
-    this._deprecationWarning =
+    this.deprecationWarning =
       process.env.NODE_ENV !== 'production' ? deprecationWarning : false;
   }
 
   /**
    * Warn the developer that he is using a deprecated action (disabled if NODE_ENV=production)
-   * 
+   *
    * @param response Result of a query to the API
-   * 
+   *
    * @returns Same as response param, just like a middleware
    */
   logDeprecation (response: ResponsePayload) {
-    if ( this._deprecationWarning
+    if ( this.deprecationWarning
       && response.deprecations
       && response.deprecations.length
     ) {
       for (const deprecation of response.deprecations) {
         // eslint-disable-next-line no-console
-        console.warn(deprecation.message);    
+        console.warn(deprecation.message);
       }
     }
     return response;

src/utils/debug.js

@@ -0,0 +1,33 @@
+function shouldDebug () {
+  if (typeof window === 'undefined') {
+    const debugString = process.env.DEBUG || '';
+
+    return debugString.includes('kuzzle-sdk');
+  }
+
+  const url = new URL(window.location);
+
+  return url.searchParams.get('debugKuzzleSdk') !== null;
+}
+
+/**
+ * Print debug only if activated
+ *
+ * In Node.js, you can set the `DEBUG=kuzzle-sdk` env variable
+ * In a browser, you can add the `?debugKuzzleSdk` in the URL
+ */
+function debug (message, obj) {
+  if (! shouldDebug()) {
+    return ;
+  }
+
+  // eslint-disable-next-line no-console
+  console.log(message);
+
+  if (obj) {
+    // eslint-disable-next-line no-console
+    console.log(JSON.stringify(obj));
+  }
+}
+
+module.exports = { debug };