@aicore/cocodb-ws-client 1.0.7 → 1.0.9

package/README.md

@@ -2,33 +2,74 @@
 WebSocket client for cocoDb. This will client can pipeline the requests to increase through put connection
 
 ## Code Guardian
-[![<app> build verification](https://github.com/aicore/template-nodejs/actions/workflows/build_verify.yml/badge.svg)](https://github.com/aicore/template-nodejs/actions/workflows/build_verify.yml)
-
-<a href="https://sonarcloud.io/summary/new_code?id=aicore_template-nodejs-ts">
-  <img src="https://sonarcloud.io/api/project_badges/measure?project=aicore_template-nodejs-ts&metric=alert_status" alt="Sonar code quality check" />
-  <img src="https://sonarcloud.io/api/project_badges/measure?project=aicore_template-nodejs-ts&metric=security_rating" alt="Security rating" />
-  <img src="https://sonarcloud.io/api/project_badges/measure?project=aicore_template-nodejs-ts&metric=vulnerabilities" alt="vulnerabilities" />
-  <img src="https://sonarcloud.io/api/project_badges/measure?project=aicore_template-nodejs-ts&metric=coverage" alt="Code Coverage" />
-  <img src="https://sonarcloud.io/api/project_badges/measure?project=aicore_template-nodejs-ts&metric=bugs" alt="Code Bugs" />
-  <img src="https://sonarcloud.io/api/project_badges/measure?project=aicore_template-nodejs-ts&metric=reliability_rating" alt="Reliability Rating" />
-  <img src="https://sonarcloud.io/api/project_badges/measure?project=aicore_template-nodejs-ts&metric=sqale_rating" alt="Maintainability Rating" />
-  <img src="https://sonarcloud.io/api/project_badges/measure?project=aicore_template-nodejs-ts&metric=ncloc" alt="Lines of Code" />
-  <img src="https://sonarcloud.io/api/project_badges/measure?project=aicore_template-nodejs-ts&metric=sqale_index" alt="Technical debt" />
+[![<app> build verification](https://github.com/aicore/cocoDbWsClient/actions/workflows/build_verify.yml/badge.svg)](https://github.com/aicore/template-nodejs/actions/workflows/build_verify.yml)
+
+<a href="https://sonarcloud.io/summary/new_code?id=aicore_cocoDbWsClient">
+  <img src="https://sonarcloud.io/api/project_badges/measure?project=aicore_cocoDbWsClient&metric=alert_status" alt="Sonar code quality check" />
+  <img src="https://sonarcloud.io/api/project_badges/measure?project=aicore_cocoDbWsClient&metric=security_rating" alt="Security rating" />
+  <img src="https://sonarcloud.io/api/project_badges/measure?project=aicore_cocoDbWsClient&metric=vulnerabilities" alt="vulnerabilities" />
+  <img src="https://sonarcloud.io/api/project_badges/measure?project=aicore_cocoDbWsClient&metric=coverage" alt="Code Coverage" />
+  <img src="https://sonarcloud.io/api/project_badges/measure?project=aicore_cocoDbWsClient&metric=bugs" alt="Code Bugs" />
+  <img src="https://sonarcloud.io/api/project_badges/measure?project=aicore_cocoDbWsClient&metric=reliability_rating" alt="Reliability Rating" />
+  <img src="https://sonarcloud.io/api/project_badges/measure?project=aicore_cocoDbWsClient&metric=sqale_rating" alt="Maintainability Rating" />
+  <img src="https://sonarcloud.io/api/project_badges/measure?project=aicore_cocoDbWsClient&metric=ncloc" alt="Lines of Code" />
+  <img src="https://sonarcloud.io/api/project_badges/measure?project=aicore_cocoDbWsClient&metric=sqale_index" alt="Technical debt" />
 </a>
 
+## Installing the library
+
+```bash
+npm install @aicore/cocodb-ws-client
+```
+
+## importing in your js file
+
+```js
+import * as coco from "@aicore/cocodb-ws-client"; // to import all functions
+```
+
+## Initializing the client
+
+Create a connection to the cocoDbServiceEndPoint and listens for messages. The connection will
+be maintained and it will try to automatically re-establish broken connections if there are network issues.
+You need to await on this function before staring to use any db APIs. Any APIs called while the connection is
+not fully setup will throw an error.
+
+### Parameters
+
+*   `cocoDbServiceEndPoint` **\[string]\[1]** The URL of the coco-db service.
+*   `authKey` **\[string]\[1]** The authKey is a base64 encoded string of the username and password.
+
+Returns **\[Promise]\[2]\<null>** Resolves when the cocodb client is ready to send/receive requests for the first time.
+Rejects only if the user calls `close` API before any connection is established.
+
+```js
+await db.init("ws://endpoint.coco", "your_auth_key");
+```
+
+## Detailed API Docs
+
+See this wiki for detailed API docs
+
+*   [https://github.com/aicore/cocoDbWsClient/wiki/api-API][1]
+*   More coco lib level detailed docs can be found at [https://github.com/aicore/libmysql/wiki/db-API][2]
+
+## close the client
+
+Closes the connection to the server. You need to await on this function before you can call init again.
+
+Returns **\[Promise]\[2]\<null>** Resolves when the cocodb client is closed and you are free to call init again. Never rejects.
+
+```js
+await db.close();
+```
+
+[1]: https://github.com/aicore/cocoDbWsClient/wiki/api-API
+
+[2]: https://github.com/aicore/libmysql/wiki/db-API
 
-# TODOs after template use
-## !!!Please see all issues in the generated repository as an issue will be generated tracking the fix of each of the below items.  
-1. Update package.json with your app defaults
-2. Check Build actions on pull requests.
-3. create a home page in wiki by going to wiki link https://github.com/<your_org>/<your_repo>/wiki
-4. Goto github `repository` > `settings`> and uncheck `Allow merge commits`. this is usually automatically done by code guardian bots in core.ai org. so you may just need to verify it.
-5. In sonar cloud, enable Automatic analysis from `Administration
-   Analysis Method` for the first time before a pull request is raised: ![image](https://user-images.githubusercontent.com/5336369/148695840-65585d04-5e59-450b-8794-54ca3c62b9fe.png)
-6. Check codacy runs on pull requests, set codacy defaults. You may remove codacy if sonar cloud is only needed.
-7. Update the above Code Guardian badges; change all `id=aicore_template-nodejs-ts` to the sonar id of your project fields. see this PR: https://github.com/aicore/libcache/pull/13
 
-# Commands available
+# Development notes
 
 ## Building
 Since this is a pure JS template project, build command just runs test with coverage.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aicore/cocodb-ws-client",
-  "version": "1.0.7",
+  "version": "1.0.9",
   "description": "Websocket client for cocoDb",
   "main": "src/index.js",
   "type": "module",
@@ -47,23 +47,23 @@
   },
   "homepage": "https://github.com/aicore/cocoDbWsClient#readme",
   "devDependencies": {
-    "@commitlint/cli": "17.1.2",
-    "@commitlint/config-conventional": "17.1.0",
+    "@commitlint/cli": "17.4.1",
+    "@commitlint/config-conventional": "17.4.0",
     "c8": "7.12.0",
-    "chai": "4.3.6",
+    "chai": "4.3.7",
     "cli-color": "2.0.3",
-    "documentation": "14.0.0",
-    "eslint": "8.25.0",
+    "documentation": "14.0.1",
+    "eslint": "8.31.0",
     "glob": "8.0.3",
-    "husky": "8.0.1",
-    "mocha": "10.0.0"
+    "husky": "8.0.3",
+    "mocha": "10.2.0"
   },
   "dependencies": {
     "@aicore/libcommonutils": "1.0.19",
-    "ws": "8.9.0"
+    "ws": "8.12.0"
   },
   "optionalDependencies": {
-    "bufferutil": "4.0.6",
-    "utf-8-validate": "5.0.9"
+    "bufferutil": "4.0.7",
+    "utf-8-validate": "5.0.10"
   }
 }

package/src/index.js

@@ -16,6 +16,8 @@
  *
  */
 
+// @INCLUDE_IN_API_DOCS
+
 export {
     get,
     init,
@@ -31,6 +33,51 @@ export {
     createTable,
     getFromNonIndex,
     hello,
-    update
+    update,
+    query
 
 } from './utils/api.js';
+
+/**
+ * ## Installing the library
+ * ```bash
+ * npm install @aicore/cocodb-ws-client
+ * ```
+ * ## importing in your js file
+ * ```js
+ * import * as coco from "@aicore/cocodb-ws-client"; // to import all functions
+ * ```
+ *
+ * ## Initializing the client
+ *
+ * Create a connection to the cocoDbServiceEndPoint and listens for messages. The connection will
+ * be maintained and it will try to automatically re-establish broken connections if there are network issues.
+ * You need to await on this function before staring to use any db APIs. Any APIs called while the connection is
+ * not fully setup will throw an error.
+ *
+ * ### Parameters
+ *
+ * *   `cocoDbServiceEndPoint` **[string][1]** The URL of the coco-db service.
+ * *   `authKey` **[string][1]** The authKey is a base64 encoded string of the username and password.
+ *
+ * Returns **[Promise][2]\<null>** Resolves when the cocodb client is ready to send/receive requests for the first time.
+ * Rejects only if the user calls `close` API before any connection is established.
+ * ```js
+ * await db.init("ws://endpoint.coco", "your_auth_key");
+ * ```
+ *
+ * ## Detailed API Docs
+ * See this wiki for detailed API docs
+ * * https://github.com/aicore/cocoDbWsClient/wiki/api-API
+ * * More coco lib level detailed docs can be found at https://github.com/aicore/libmysql/wiki/db-API
+ *
+ * ## close the client
+ *
+ * Closes the connection to the server. You need to await on this function before you can call init again.
+ *
+ * Returns **[Promise][2]\<null>** Resolves when the cocodb client is closed and you are free to call init again. Never rejects.
+ * ```js
+ * await db.close();
+ * ```
+ * @module @aicore/cocodb-ws-client
+ */

package/src/utils/client.js

@@ -1,19 +1,132 @@
 import {WS} from "./WebSocket.js";
 import {isString, isObject, isStringEmpty, COCO_DB_FUNCTIONS} from "@aicore/libcommonutils";
 
-let client = null;
+let client = null,
+    cocoDBEndPointURL = null,
+    cocoAuthKey = null;
 const WEBSOCKET_ENDPOINT_COCO_DB = '/ws/';
 const ID_TO_RESOLVE_REJECT_MAP = {};
+const CONNECT_BACKOFF_TIME_MS = [1, 500, 1000, 3000, 5000, 10000, 20000];
 let id = 0;
 
+let currentBackoffIndex = 0;
+function _resetBackoffTime() {
+    currentBackoffIndex = 0;
+}
+function _getBackoffTime() {
+    if(currentBackoffIndex >= CONNECT_BACKOFF_TIME_MS.length){
+        currentBackoffIndex = CONNECT_BACKOFF_TIME_MS.length - 1;
+    }
+    return CONNECT_BACKOFF_TIME_MS[currentBackoffIndex++];
+}
+
 // @INCLUDE_IN_API_DOCS
 
+
 /**
- * It creates a websocket connection to the cocoDbServiceEndPoint and listens for messages
+ * Sets up the websocket client and returns a promise that will be resolved when the connection is closed or broken.
+ *
+ * @param {function} connectedCb a callbak that will be executed when a connection is established to db
+ * @return {Promise<null>} promise that will be resolved when the connection is closed/broken/error.
+ * @private
+ */
+function _setupClientAndWaitForClose(connectedCb) {
+    return new Promise(resolve =>{
+        client = new WS.WebSocket(cocoDBEndPointURL.trim() + WEBSOCKET_ENDPOINT_COCO_DB, {
+            perMessageDeflate: false,
+            headers: {
+                Authorization: `Basic ${cocoAuthKey}`
+            }
+        });
+        client.on('open', function open() {
+            console.log('connected to server');
+            client.connectionEstablished = true;
+            connectedCb && connectedCb();
+        });
+
+        client.on('message', function message(data) {
+            __receiveMessage(data);
+        });
+
+        function _connectionTerminated(reason) {
+            console.log(reason);
+            client.connectionEstablished = false;
+            for (let sequenceNumber in ID_TO_RESOLVE_REJECT_MAP) {
+                let rejectHandler = ID_TO_RESOLVE_REJECT_MAP[sequenceNumber].reject;
+                rejectHandler(reason);
+                delete ID_TO_RESOLVE_REJECT_MAP[sequenceNumber];
+            }
+            resolve();
+        }
+        client.on('close', function () {
+            // https://websockets.spec.whatwg.org/#eventdef-websocket-error
+            // https://stackoverflow.com/questions/40084398/is-onclose-always-called-after-onerror-for-websocket
+            // we do not need to listen for error event as an error event is immediately followed by a close event.
+            _connectionTerminated('connection closed');
+        });
+    });
+}
+
+let backoffTimer = null, backoffResolveFn = null;
+function _backoffTimer(timeInMilliSec) {
+    return new Promise(resolve => {
+        backoffResolveFn = resolve;
+        backoffTimer = setTimeout(()=>{
+            backoffTimer = null;
+            backoffResolveFn = null;
+            resolve();
+        }, timeInMilliSec);
+    });
+}
+
+function _cancelBackoffTimer() {
+    _resetBackoffTime();
+    if(backoffTimer){
+        clearTimeout(backoffTimer);
+        backoffTimer = null;
+        backoffResolveFn();
+        backoffResolveFn = null;
+    }
+}
+
+async function _setupAndMaintainConnection(firstConnectionCb, neverConnectedCB) {
+    backoffTimer = null;
+    function connected() {
+        _resetBackoffTime();
+        if(firstConnectionCb){
+            firstConnectionCb("connected");
+            firstConnectionCb = null;
+        }
+    }
+    while(!client || !client.userClosedConnection){
+        await _setupClientAndWaitForClose(connected);
+        if(!client || !client.userClosedConnection){
+            await _backoffTimer(_getBackoffTime());
+        }
+    }
+    client.userClosedConnectionCB && client.userClosedConnectionCB();
+    client = cocoDBEndPointURL = cocoAuthKey = null;
+    id = 0;
+    if(neverConnectedCB){
+        neverConnectedCB(new Error("user Cancelled"));
+    }
+}
+
+/**
+ * Create a connection to the cocoDbServiceEndPoint and listens for messages. The connection will
+ * be maintained and it will try to automatically re-establish broken connections if there are network issues.
+ * You need to await on this function before staring to use any db APIs. Any APIs called while the connection is
+ * not fully setup will throw an error.
+ *
  * @param {string} cocoDbServiceEndPoint - The URL of the coco-db service.
  * @param {string} authKey - The authKey is a base64 encoded string of the username and password.
+ * @return {Promise<null>} Resolves when the cocodb client is ready to send/receive requests for the first time.
+ * Rejects only if the user calls `close` API before any connection is established.
  */
 export function init(cocoDbServiceEndPoint, authKey) {
+    if(client) {
+        throw new Error('Please close the existing connection before calling init again');
+    }
     if (isStringEmpty(cocoDbServiceEndPoint) || !(cocoDbServiceEndPoint.startsWith('ws://')
         || cocoDbServiceEndPoint.startsWith('wss://'))) {
         throw new Error('Please provide valid cocoDbServiceEndPoint');
@@ -21,40 +134,37 @@ export function init(cocoDbServiceEndPoint, authKey) {
     if (isStringEmpty(authKey)) {
         throw new Error('Please provide valid authKey');
     }
-    client = new WS.WebSocket(cocoDbServiceEndPoint.trim() + WEBSOCKET_ENDPOINT_COCO_DB, {
-        perMessageDeflate: false,
-        headers: {
-            Authorization: `Basic ${authKey}`
-        }
-    });
-    client.on('open', function open() {
-        console.log('connected to server');
-    });
-
-    client.on('message', function message(data) {
-        __receiveMessage(data);
-    });
-    client.on('close', function terminate() {
-        console.log('closing connection');
-        for (let sequenceNumber in ID_TO_RESOLVE_REJECT_MAP) {
-            let reject = ID_TO_RESOLVE_REJECT_MAP[sequenceNumber].reject;
-            reject('connection closed');
-            delete ID_TO_RESOLVE_REJECT_MAP[sequenceNumber];
-        }
-        client = null;
-        id = 0;
+    cocoDBEndPointURL = cocoDbServiceEndPoint;
+    cocoAuthKey = authKey;
+    return new Promise((resolve, reject) => {
+        _setupAndMaintainConnection(resolve, reject);
     });
 }
 
 /**
- * It closes the connection to the server
- * @returns The function close() is being returned.
+ * Closes the connection to the server. You need to await on this function before you can call init again.
+ *
+ * @return {Promise<null>} Resolves when the cocodb client is closed and you are free to call init again. Never rejects.
  */
 export function close() {
-    if (!client) {
-        return;
+    // we need to save the current client for the callback function hooks below. the global client may change
+    // as init and close gets called by the user.
+    let currentClient = client;
+    if (!currentClient) {
+        return Promise.resolve();
     }
-    client.terminate();
+    if(currentClient.closePromise){
+        return currentClient.closePromise;
+    }
+    currentClient.closePromise = new Promise((resolve)=>{
+        currentClient.userClosedConnection = true;
+        currentClient.userClosedConnectionCB = function () {
+            resolve();
+        };
+        _cancelBackoffTimer(); // this is for if the connection is broken and, we are retrying the connection
+        currentClient.terminate();
+    });
+    return currentClient.closePromise;
 }
 
 /**
@@ -78,6 +188,10 @@ export function sendMessage(message) {
             reject('Please call init before sending message');
             return;
         }
+        if (!client.connectionEstablished) {
+            reject('Db connection is not ready, please retry in some time');
+            return;
+        }
         if (!isObject(message)) {
             reject('Please provide valid Object');
             return;