Websocket-manager

This is the websocket infrastucture for our servers. It provides a class which will attached a websocket to your express server. You may then set up endpoints and clients as you please.

Table of Contents

1. Table of Contents
2. Required Technologies
3. Installation
4. Useage
5. API

Required Technologies

• Node / NPM: Node version 12 or greater is recommended.
• Express: You should use express for your webserver. The constructor for SocketManager takes a server instance which you can get via server = app.listen(...)

Installation

To install, run:

npm install @dataquiver/websocket-manager --save

Useage

The intent of this package is to make websockets easy to use, and easy to integrate with the @dataquiver/mongo package.

1. To initialize a socketManager all you must do is construct it with your middleware function (likely from @dataquiver/middleware). Then initialize it with your server instance

   const socketManager = new SocketManager(socketMiddleware.middleware);
   await socketManager.init(server);

API

socketManager.addEventListener(event, callback)

addEventListener is how you tell socketManager to listen to events from the client.

• event
  • your event string
• callback
  • the function to execute when a the client hits the event
  • must return a promise
  • will be passed parameters callback(requestData, user)
    • the user object will be added to every client in the middleware, and passed to all callbacks so you may do accessControl and filtering.

socketManager.clients

• Object
• key: socketio clientId
• value: socketio client socket

This is useful if you want to emit asynchronous events to those clients like:

// Promisified loop over clients object
return Promise.all(Object.keys(this.socketManager.clients).map((socketId) => {
  //get the client's socket
  const clientSocket = this.socketManager.clients[socketId];

  // ensure the client may receive this data
  return this.filterFunction(clientSocket.user, event, data)
  .then(() => {
    // emit the event
    clientSocket.emit(`coolSocketEvent`, data);
  })
  .catch((e) => {
    // do not emit the event
    console.log('I shal not emit to you', e);
  });
}));

Middleware

This expects a middleware which will be ran when a client attempts to connect. It is expected that this middleware add a user to the socket. If you do not want/need this, mock a user object in your middleware. Sorry :\

We have a socketMiddleware that works with AWS cognito at @dataquiver/middleware

Contributing

1. Clone this repo
2. Run npm install to download dependencies
3. Run npm run build to compile typescript into javascript for distribution
4. Run npm run lint to run lint checks. This is also in a pre-commit hook.

Publishing

1. Run npm publish to publish to npm. You'll need to be authorized. This ought to run the build automatically.

Testing in an app

1. In this repo, run npm link to register it for overriding
2. In the app, run npm link @dataquiver/websocket-manager to override the package from NPM with a symlink to this local copy
3. Run your app

If you make changes, you'll need to run npm run build in this repo and likely restart your app to pick them up.

When you're done, in the app, run npm unlink @dataquiver/websocket-manager --no-save to remove the symlink and go back to using the NPM package. Use npm install then to redownload from the internet.