@aicore/cocodb-ws-client 1.0.8 → 1.0.10

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.8",
+  "version": "1.0.10",
   "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.2",
+    "@commitlint/config-conventional": "17.4.2",
     "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",
-    "glob": "8.0.3",
-    "husky": "8.0.1",
-    "mocha": "10.1.0"
+    "documentation": "14.0.1",
+    "eslint": "8.33.0",
+    "glob": "8.1.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.7",
-    "utf-8-validate": "5.0.10"
+    "utf-8-validate": "6.0.2"
   }
 }

package/src/index.js

@@ -16,6 +16,8 @@
  *
  */
 
+// @INCLUDE_IN_API_DOCS
+
 export {
     get,
     init,
@@ -35,3 +37,47 @@ export {
     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,191 @@
 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,
+    hibernateTimer = null,
+    bufferRequests = false,
+    pendingSendMessages = [];
+const MAX_PENDING_SEND_BUFFER_SIZE = 2000;
 const WEBSOCKET_ENDPOINT_COCO_DB = '/ws/';
-const ID_TO_RESOLVE_REJECT_MAP = {};
-let id = 0;
+const ID_TO_RESOLVE_REJECT_MAP = new Map();
+const CONNECT_BACKOFF_TIME_MS = [1, 500, 1000, 3000, 5000, 10000, 20000];
+const INACTIVITY_TIME_FOR_HIBERNATE = 8000;
+let id = 0, activityInHibernateInterval = 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
 
+
+function _checkActivityForHibernation() {
+    if(activityInHibernateInterval > 0){
+        activityInHibernateInterval = 0;
+        return;
+    }
+    if(!client || client.hibernating
+        || !client.connectionEstablished // cant hibernate if connection isnt already established/ is being establised
+        || ID_TO_RESOLVE_REJECT_MAP.size > 0){ // if there are any pending responses, we cant hibernate
+        return;
+    }
+    // hibernate
+    client.hibernating = true;
+    client.hibernatingPromise = new Promise((resolve=>{
+        client.hibernatingPromiseResolve = resolve;
+    }));
+    bufferRequests = true;
+    client.terminate();
+}
+
+/**
+ * returns a promise that resolves when hibernation ends.
+ * @return {Promise<unknown>}
+ * @private
+ */
+function _toAwakeFromHibernate() {
+    return client.hibernatingPromise;
+}
+
+function _wakeupHibernatingClient() {
+    if(client.hibernatingPromiseResolved) {
+        return;
+    }
+    client.hibernatingPromiseResolve();
+    client.hibernatingPromiseResolved = true;
+}
+
+/**
+ * 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;
+            bufferRequests = false;
+            connectedCb && connectedCb();
+            _sendPendingMessages();
+        });
+
+        client.on('message', function message(data) {
+            __receiveMessage(data);
+        });
+
+        function _connectionTerminated(reason) {
+            console.log(reason);
+            client.connectionEstablished = false;
+            for (let [sequenceNumber, handler] of ID_TO_RESOLVE_REJECT_MAP) {
+                handler.reject(reason);
+                ID_TO_RESOLVE_REJECT_MAP.delete(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;
+            // setup hibernate timer on first connection
+            activityInHibernateInterval = 1;
+            hibernateTimer = setInterval(_checkActivityForHibernation, INACTIVITY_TIME_FOR_HIBERNATE);
+        }
+    }
+    while(!client || !client.userClosedConnection){
+        await _setupClientAndWaitForClose(connected);
+        if(client && client.hibernating && !client.userClosedConnection){
+            await _toAwakeFromHibernate();
+            continue;
+        }
+        if(!client || !client.userClosedConnection){
+            await _backoffTimer(_getBackoffTime());
+        }
+    }
+    if(hibernateTimer){
+        clearInterval(hibernateTimer);
+        hibernateTimer = null;
+    }
+    client && client.userClosedConnectionCB && client.userClosedConnectionCB();
+    client = cocoDBEndPointURL = cocoAuthKey = null;
+    id = 0;
+    if(neverConnectedCB){
+        neverConnectedCB(new Error("user Cancelled"));
+    }
+}
+
 /**
- * It creates a websocket connection to the cocoDbServiceEndPoint and listens for messages
+ * 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.
+ *
+ * ## Hibernation after inactivity
+ * After around 10 seconds of no send activity and if there are no outstanding requests, the db connection will be
+ * dropped and the client move into a hibernation state. The connection will be immediately re-established on any
+ * db activity transparently, though a slight jitter may be observed during the connection establishment time. This
+ * auto start-stop will save database resources as servers can be on for months on end.
+ *
  * @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 +193,45 @@ 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 () {
+            for(let entry of pendingSendMessages){
+                entry.reject();
+            }
+            pendingSendMessages = [];
+            resolve();
+        };
+        _cancelBackoffTimer(); // this is for if the connection is broken and, we are retrying the connection
+        if(currentClient.hibernating){
+            _wakeupHibernatingClient();
+        } else {
+            currentClient.terminate();
+        }
+    });
+    return currentClient.closePromise;
 }
 
 /**
@@ -66,6 +243,39 @@ function getId() {
     return id.toString(16);
 }
 
+function _sendMessage(message, resolve, reject) {
+    if (!client) {
+        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;
+    }
+    if (!isString(message.fn) || !(message.fn in COCO_DB_FUNCTIONS)) {
+        reject('please provide valid function name');
+        return;
+    }
+    const sequenceNumber = getId();
+    message.id = sequenceNumber;
+    ID_TO_RESOLVE_REJECT_MAP.set(sequenceNumber, {
+        resolve: resolve,
+        reject: reject
+    });
+    activityInHibernateInterval++;
+    client.send(JSON.stringify(message));
+}
+
+function _sendPendingMessages() {
+    for(let entry of pendingSendMessages){
+        _sendMessage(entry.message, entry.resolve, entry.reject);
+    }
+    pendingSendMessages = [];
+}
 
 /**
  * It takes a message object, sends it to the server, and returns a promise that resolves when the server responds
@@ -74,25 +284,18 @@ function getId() {
  */
 export function sendMessage(message) {
     return new Promise(function (resolve, reject) {
-        if (!client) {
-            reject('Please call init before sending message');
-            return;
-        }
-        if (!isObject(message)) {
-            reject('Please provide valid Object');
-            return;
+        if(bufferRequests){
+            if(pendingSendMessages.length > MAX_PENDING_SEND_BUFFER_SIZE){
+                reject('Too many requests sent while waking up from hibernation');
+                return;
+            }
+            pendingSendMessages.push({message, resolve, reject});
+            if(client&& client.hibernating){
+                _wakeupHibernatingClient();
+            }
+        } else {
+            _sendMessage(message, resolve, reject);
         }
-        if (!isString(message.fn) || !(message.fn in COCO_DB_FUNCTIONS)) {
-            reject('please provide valid function name');
-            return;
-        }
-        const sequenceNumber = getId();
-        message.id = sequenceNumber;
-        ID_TO_RESOLVE_REJECT_MAP[sequenceNumber] = {
-            resolve: resolve,
-            reject: reject
-        };
-        client.send(JSON.stringify(message));
     });
 }
 
@@ -111,15 +314,14 @@ export function __receiveMessage(rawData) {
         console.error('Server message does not have an Id');
         return false;
     }
-    const requestResolve = ID_TO_RESOLVE_REJECT_MAP[message.id];
-    if (!isObject(requestResolve)) {
+    const requestHandler = ID_TO_RESOLVE_REJECT_MAP.get(message.id);
+    if (!isObject(requestHandler)) {
         //TODO: Emit metrics
 
         console.error(`Client did not send message with Id ${message.id} to server`);
         return false;
     }
-    const response = message.response;
-    requestResolve.resolve(response);
-    delete ID_TO_RESOLVE_REJECT_MAP[message.id];
+    requestHandler.resolve(message.response);
+    ID_TO_RESOLVE_REJECT_MAP.delete(message.id);
     return true;
 }