module:api/ws

Description:

• Websockets requests as Express routes

  The simplest way is to configure api-ws-port to the same value as the HTTP port. This will run WebSockets server along the regular Web server.

  Usage

  var ws = new WebSocket("http://localhost:8000/ws");
  ws.onmessage = (msg) => { console.log(msg) }
  

  There are two ways to send messages via Websockets to the server from a browser:

  1. as Urls

  ws.send('/project/update?id=1&name=Test2')
  

  In this case the url will be parsed and checked for access and authorization before letting it pass via Express routes. This method allows to share the same route handlers between HTTP and Websockets requests, the handlers will use the same code and all responses will be sent back, only in the Websockets case the response will arrived in the message listener (see an example below)

  2. as JSON objects, format can be any

  ws.send({ op: "/project/update", project: { id: 1, name: "Test2" } })```
  

  In this case the server still have to check for access so it treats all JSON messages as coming from the path which was used during the connect, i.e. the one used in the above /ws. The Express route handler for this path will receive all messages from Websocket clients, the response will be received in the event listener the same way as for the first use case.

  // Notify all clients who is using the project being updated
  api.app.all("/ws", (req, res) => {
     switch (req.query.op) {
     case "/project/update":
        //  some code ....
        api.ws.notify({ query: { id: req.query.project.id } }, { op: "/project/update", project: req.query.project });
        break;
     }
     res.send("");
  });
  

  In any case all Websocket messages sent from the server will arrive in the event handler and must be formatted properly in order to distinguish what is what, this is the application logic. If the server needs to send a message to all or some specific clients for example due to some updates in the DB, it must use the module:api/ws.notify function.

  // Received a new message for a user from external API service, notify all websocket clients by user id
  api.app.post("/api/message", (req, res) => {
     ....
     ... processing logic
     ....
     api.ws.notify({ user_id: req.query.uid }, { op: "/message/new", msg: req.query.msg });
  });
  

Source:

• api/ws.js, line 81